MCP Code Assistant

A minimal Model Context Protocol (MCP) server implementation in Python that provides developer tools for file operations, C code compilation, and executable execution.

A learning project for understanding how to build MCP servers from scratch. Designed with an extensible architecture for future enhancements.

Overview

This MCP server communicates using JSON-RPC 2.0 over stdin/stdout, making it compatible with MCP clients and AI assistants that support the Model Context Protocol.

Features

• File Operations

  • read_file: Read contents from any file on the filesystem
  • write_file: Write contents to files (with automatic directory creation)

• Future Tools (extensible architecture)

  • Compile C code
  • Run executables
  • Debug tools

Project Structure

mcp-code-assistant/
├── server.py           # Main MCP server implementation
├── logger.py           # Logging utilities (writes to stderr)
├── jsonrpc.py          # JSON-RPC 2.0 message handling
├── dispatcher.py       # Tool registration and dispatch
├── tools/              # Tool implementations
│   ├── __init__.py     # Tools package
│   └── file_ops.py     # File operation tools
├── requirements.txt    # Python dependencies (minimal)
└── README.md           # This file

Requirements

• Python 3.7 or higher
• No external dependencies (uses only Python standard library)

Installation

1. Clone or download this project
2. No installation needed - uses only stdlib

cd mcp-code-assistant

Usage

Running the Server

The server reads JSON-RPC requests from stdin and writes responses to stdout:

python3 server.py

Testing the Server

You can test the server manually by sending JSON-RPC requests via stdin:

# Start the server
python3 server.py

# Then type (or pipe) JSON-RPC requests:
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "clientInfo": {"name": "test-client", "version": "1.0"}}}

{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}

{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "read_file", "arguments": {"path": "README.md"}}}

Using with MCP Clients

Configure your MCP client to run this server. Example configuration:

{
  "mcpServers": {
    "code-assistant": {
      "command": "python3",
      "args": ["/path/to/mcp-code-assistant/server.py"]
    }
  }
}

Available Tools

read_file

Reads the contents of a file from the filesystem.

Parameters:

• path (string, required): Path to the file (absolute or relative)

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "/home/user/example.txt"
    }
  }
}

write_file

Writes contents to a file on the filesystem. Creates parent directories if needed.

Parameters:

• path (string, required): Path to the file
• contents (string, required): Contents to write

Example:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "write_file",
    "arguments": {
      "path": "/home/user/output.txt",
      "contents": "Hello, World!"
    }
  }
}

Development

Adding New Tools

1. Create a new file in tools/ (e.g., compile_ops.py)
2. Define your tool handler functions
3. Create a TOOLS dictionary with tool definitions
4. Import and register in tools/__init__.py

Example tool structure:

def my_tool(args):
    """Tool implementation."""
    # Validate args
    # Perform operation
    # Return result dict
    return {"result": "success"}

TOOLS = {
    "my_tool": {
        "handler": my_tool,
        "description": "Description of what the tool does",
        "inputSchema": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Parameter description"
                }
            },
            "required": ["param1"]
        }
    }
}

Logging

All logs go to stderr to keep stdout clean for JSON-RPC communication. Use the logger module:

from logger import log_info, log_error, log_debug

log_info("Server started")
log_debug("Debug message")
log_error("Error message")

Protocol Support

• Protocol Version: 2024-11-05
• JSON-RPC: 2.0
• Methods Supported:
  • initialize: Initialize the server connection
  • tools/list: List all available tools
  • tools/call: Execute a tool

License

This is a minimal educational implementation. Use and modify as needed.

Future Enhancements

• [ ] C code compilation tool (compile_c)
• [ ] Execute binary tool (run_executable)
• [ ] Debugging tools
• [ ] Code analysis tools
• [ ] Git integration
• [ ] Project scaffolding tools