# 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

```bash
cd mcp-code-assistant
```

## Usage

### Running the Server

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

```bash
python3 server.py
```

### Testing the Server

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

```bash
# 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:

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:

```python
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:

```python
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