Poly MCP Documentation

A comprehensive MCP (Model Context Protocol) server with extensive tooling for filesystem operations, diagnostics, scripting, time management, network utilities, context handling, git operations, and user input.

What is Poly MCP?

Poly MCP is a production-ready Model Context Protocol server that provides AI assistants with full access to system operations, development tools, and automation capabilities. It bridges the gap between AI models and system-level operations through a clean, well-documented JSON-RPC 2.0 interface.

Key Features

🎯 Language-Agnostic Design

Every module in Poly MCP is designed to work across multiple programming languages and environments. Whether you're working with Rust, TypeScript, Python, or C++, Poly MCP provides consistent tooling.

🔒 Production-Ready

Built with robust error handling, comprehensive logging, and battle-tested libraries like libgit2, Poly MCP is ready for production use in critical environments.

📦 Modular Architecture

Each of the 8 modules operates independently, allowing you to use only what you need. Modules don't have hidden dependencies or unexpected side effects.

⚡ High Performance

Written in Rust for maximum performance, Poly MCP handles concurrent operations efficiently and maintains low memory overhead.

Architecture Overview

Poly MCP follows the Model Context Protocol specification, communicating via JSON-RPC 2.0 over stdin/stdout. This design allows seamless integration with any MCP-compatible AI system.

┌─────────────────┐
│   AI Assistant  │
└────────┬────────┘
         │ JSON-RPC 2.0
         │ (stdin/stdout)
┌────────▼────────┐
│   Poly MCP      │
│   Server        │
├─────────────────┤
│ • Filesystem    │
│ • Diagnostics   │
│ • Silent        │
│ • Time          │
│ • Network       │
│ • Context       │
│ • Git           │
│ • Input         │
└─────────────────┘

Core Modules

Filesystem Module

Advanced file and directory operations with snapshot management, permissions handling, and real-time file watching. Perfect for managing codebases, data files, and system configurations.

Key Features:

  • Atomic file operations
  • Timestamped snapshots with auto-rotation
  • Pattern-based file search
  • Unix permissions management
  • Real-time file change monitoring

Diagnostics Module

Language-agnostic error and warning detection that automatically identifies the appropriate diagnostic tool for your project. Supports Rust, TypeScript, JavaScript, Python, C, and C++.

Key Features:

  • Auto-detection of project type
  • Structured error output
  • Integration with cargo, tsc, eslint, pylint, flake8, gcc, and clang
  • Detailed error location (file, line, column)
  • Severity levels and error codes

Silent Module

Execute bash scripts with full control over arguments, environment variables, and timeouts. Monitor system resources including GPU, RAM, and CPU usage with detailed process information.

Key Features:

  • Script execution with custom environments
  • Configurable timeouts
  • NVIDIA GPU monitoring via nvidia-smi
  • Process filtering and sorting
  • Resource usage tracking

Time Module

Comprehensive time management and task scheduling with support for multiple timestamp formats and in-memory task scheduling.

Key Features:

  • Multiple timestamp formats (Unix, ISO8601, RFC3339, custom)
  • In-memory task scheduler
  • Task creation, cancellation, and monitoring
  • Configurable delays and intervals

Network Module

HTTP requests with automatic HTML-to-Markdown conversion and package registry queries for Rust, Node.js, Python, and APT packages.

Key Features:

  • Automatic HTML to Markdown conversion
  • Package metadata from crates.io, npm, PyPI, and APT
  • Network connectivity testing
  • Version queries and dependency resolution

Context Module

Token counting and cost estimation for various LLM providers, with support for text compression and in-memory data storage.

Key Features:

  • Token counting for GPT-4, Claude, Gemini, LLaMA, and more
  • API cost estimation for major providers
  • Text compression (gzip, zlib)
  • In-memory key-value store
  • Context usage tracking

Git Module

Complete git operations powered by libgit2, providing reliable version control capabilities without shell command dependencies.

Key Features:

  • Full libgit2 integration
  • Branch management
  • Commit history and diffs
  • File blame with authorship
  • Tag management (lightweight and annotated)
  • Status tracking

Input Module

User interaction through prompts, selections, notifications, and clipboard operations. Support for both terminal and desktop notifications.

Key Features:

  • Interactive text prompts
  • Selection menus
  • Terminal and desktop notifications
  • Clipboard read/write
  • Progress bars
  • Configurable urgency levels

Installation

From crates.io

cargo install poly-mcp

From source

git clone https://github.com/polysystems/mcp
cd poly-mcp
cargo build --release

The binary will be available at target/release/poly-mcp.

Quick Start

Starting the Server

poly-mcp

The server will listen on stdin and output to stdout following the MCP protocol.

Basic Workflow

  1. Initialize the connection:
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}
  1. List available tools:
{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}
  1. Call a tool:
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "fs_read",
    "arguments": {
      "path": "/path/to/file.txt"
    }
  }
}

Configuration

Poly MCP can be configured through environment variables:

  • POLY_MCP_LOG_LEVEL - Set logging level (debug, info, warn, error)
  • POLY_MCP_MAX_SNAPSHOTS - Default maximum number of snapshots to keep
  • POLY_MCP_TIMEOUT - Default timeout for script execution (seconds)

Error Handling

All tools follow a consistent error handling pattern:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32000,
    "message": "File not found: /path/to/file.txt",
    "data": {
      "tool": "fs_read",
      "path": "/path/to/file.txt"
    }
  }
}

Best Practices

1. Always Check Return Values

Every tool call returns a structured response. Always check for errors before processing results.

2. Use Appropriate Timeouts

When executing scripts or long-running operations, set appropriate timeouts to prevent hanging.

3. Handle File Paths Carefully

Always use absolute paths when possible. Relative paths are resolved from the server's working directory.

4. Monitor Resource Usage

Use the silent_resources tool to monitor system resources before running intensive operations.

5. Create Snapshots Before Modifications

Use fs_snapshot before making significant file system changes to enable easy rollback.

Security Considerations

File System Access

Poly MCP has full access to the file system. Use appropriate permissions and sandboxing when running in production environments.

Script Execution

The silent_script tool executes bash scripts with full system access. Validate and sanitize script content before execution.

Network Operations

Network tools can access any URL. Consider implementing network policies or firewall rules for production deployments.

Performance Tips

1. Batch Operations

When performing multiple file operations, consider using pattern matching with fs_find instead of individual calls.

2. Use Streaming for Large Files

For large files, consider reading in chunks rather than loading entire contents into memory.

3. Cache Package Queries

Package registry queries can be slow. Cache results when querying the same packages multiple times.

4. Limit Concurrent Operations

While Poly MCP supports concurrent operations, limit the number of simultaneous tool calls to avoid resource exhaustion.

Troubleshooting

Tool Not Found

Ensure the tool name is spelled correctly. Use tools/list to see all available tools.

File Access Denied

Check file permissions and ensure the server process has appropriate access rights.

Timeout Errors

Increase timeout values for long-running operations or optimize the operation.

Network Errors

Check network connectivity and firewall settings. Some package registries may rate-limit requests.

Contributing

Contributions are welcome! Please see our GitHub repository for:

  • Bug reports and feature requests
  • Pull requests
  • Documentation improvements
  • Example use cases

License

Licensed under the MIT License. See LICENSE file for details.

Support

Next Steps