README.md•4.96 kB
# 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