README.md•7.77 kB
# Spec3 MCP Server
A Model Context Protocol (MCP) server built with FastMCP for local development and testing with Claude Desktop on WSL.
## Overview
This MCP server provides a set of tools and utilities that can be used by Claude Desktop through the MCP protocol. It's designed to run locally on your WSL machine and connect to Claude Desktop via stdio.
## Features
- **Modern Python Project Structure**: Uses `pyproject.toml` and follows Python packaging best practices
- **FastMCP Integration**: Built on the FastMCP framework for easy MCP protocol handling
- **Multiple Tools**: Includes basic demonstration and utility tools
- **Comprehensive Logging**: Detailed logging for debugging and monitoring
- **Type Hints**: Full type annotation support for better development experience
- **WSL Compatible**: Runs seamlessly on WSL and connects to Claude Desktop
## Available Tools
1. **hello_world**: Returns a simple greeting message
2. **echo_message**: Echoes back a message with additional formatting
3. **get_server_info**: Returns comprehensive server information and capabilities
4. **list_available_tools**: Lists all available tools with descriptions
## Installation
### Prerequisites
- Python 3.10 or higher
- WSL (Windows Subsystem for Linux)
- Claude Desktop (installed on Windows)
### Setup
1. **Navigate to the project directory:**
```bash
cd /home/dhevb/workspaces/spec3-mcp-server
```
2. **Create and activate a virtual environment:**
```bash
python -m venv venv
source venv/bin/activate
```
3. **Install the package in development mode:**
```bash
pip install -e .
```
This will install the package and all its dependencies, including FastMCP.
4. **Verify the installation:**
```bash
spec3-mcp-server --help
```
## Connecting to Claude Desktop
### Configure Claude Desktop on Windows
1. **Locate your Claude Desktop config file:**
- On Windows, it's typically at: `%APPDATA%\Claude\claude_desktop_config.json`
- Full path is usually: `C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json`
2. **Edit the configuration file** and add the following:
```json
{
"mcpServers": {
"spec3-mcp-server": {
"command": "wsl",
"args": [
"-e",
"/home/dhevb/workspaces/spec3-mcp-server/venv/bin/python",
"/home/dhevb/workspaces/spec3-mcp-server/src/spec3_mcp_server/main.py"
],
"env": {}
}
}
}
```
**Note**: The `wsl` command allows Claude Desktop on Windows to execute Python in your WSL environment.
3. **Restart Claude Desktop** to load the new configuration
4. **Verify the connection:**
- Open Claude Desktop
- Start a new conversation
- Look for the MCP tools icon or hammer icon
- You should see the spec3-mcp-server tools available
### Alternative: Using Installed Command
If you prefer to use the installed `spec3-mcp-server` command:
```json
{
"mcpServers": {
"spec3-mcp-server": {
"command": "wsl",
"args": [
"-e",
"/home/dhevb/workspaces/spec3-mcp-server/venv/bin/spec3-mcp-server"
]
}
}
}
```
## Testing the Server
### Test Locally (Without Claude Desktop)
You can test the server locally to ensure it's working:
```bash
# Activate your virtual environment
source venv/bin/activate
# Run the server directly
python src/spec3_mcp_server/main.py
```
The server will start and wait for MCP messages on stdin. You can verify it's running if you see the startup logs.
### Test with Claude Desktop
Once connected to Claude Desktop, you can test the tools by asking Claude to use them:
- "Use the hello_world tool"
- "Echo this message: Hello from WSL!"
- "Get server information"
- "List all available tools"
## Development
### Project Structure
```
spec3-mcp-server/
├── src/
│ └── spec3_mcp_server/
│ ├── __init__.py # Package initialization
│ ├── main.py # Main entry point
│ ├── server.py # MCP server implementation
│ └── http_server.py # HTTP server (for network access)
├── tests/ # Test files (to be added)
├── pyproject.toml # Project configuration
├── README.md # This file
├── claude_desktop_config.json # Example config for Claude Desktop
└── .gitignore # Git ignore rules
```
### Adding New Tools
To add new tools to the MCP server:
1. **Edit `src/spec3_mcp_server/server.py`**
2. **Add a new tool function decorated with `@mcp.tool()`**
3. **Add proper type hints and docstring**
Example:
```python
@mcp.tool()
async def my_new_tool(param: str) -> str:
"""
Description of what this tool does.
Args:
param: Description of the parameter
Returns:
str: Description of the return value
"""
logger.info(f"my_new_tool called with: {param}")
return f"Processed: {param}"
```
4. **Reinstall the package** (if needed):
```bash
pip install -e .
```
5. **Restart Claude Desktop** to load the updated tools
### Code Quality
The project includes configuration for:
- **Black**: Code formatting
- **isort**: Import sorting
- **mypy**: Type checking
- **ruff**: Linting
- **pytest**: Testing
Run quality checks:
```bash
# Format code
black src/
# Sort imports
isort src/
# Type checking
mypy src/
# Linting
ruff check src/
# Run tests (when added)
pytest
```
## Troubleshooting
### Common Issues
1. **Server won't start:**
- Check that Python 3.10+ is installed in WSL: `python --version`
- Ensure FastMCP is installed: `pip install fastmcp`
- Verify virtual environment is activated: `which python`
2. **Claude Desktop can't connect:**
- Verify the paths in `claude_desktop_config.json` are correct
- Check that WSL is accessible from Windows
- Look at Claude Desktop's logs for connection errors
- Test the server manually in WSL first
3. **Tools not appearing:**
- Restart Claude Desktop after configuration changes
- Check server logs for errors
- Verify the server is running: `ps aux | grep spec3-mcp-server`
4. **WSL-specific issues:**
- Ensure WSL is properly installed: `wsl --version`
- Test WSL execution from Windows CMD: `wsl -e python --version`
- Check WSL distro is running: `wsl -l -v`
### Logging
The server includes comprehensive logging. Check the console output for:
- Server startup messages
- Tool execution logs
- Error messages and stack traces
To see logs when running via Claude Desktop, you can redirect them to a file by modifying the config:
```json
{
"mcpServers": {
"spec3-mcp-server": {
"command": "wsl",
"args": [
"-e",
"/bin/bash",
"-c",
"/home/dhevb/workspaces/spec3-mcp-server/venv/bin/python /home/dhevb/workspaces/spec3-mcp-server/src/spec3_mcp_server/main.py 2>> /home/dhevb/workspaces/spec3-mcp-server/mcp-server.log"
]
}
}
}
```
### Getting Help
If you encounter issues:
1. Check the server logs for error messages
2. Verify your Python and FastMCP versions
3. Test the server independently before connecting to Claude Desktop
4. Check the FastMCP documentation at https://github.com/jlowin/fastmcp
5. Review Claude Desktop's documentation for MCP configuration
## Next Steps
Once you have the local server working:
1. **Add more sophisticated tools** for your specific use cases
2. **Implement error handling** for robust operation
3. **Add tests** to ensure reliability
4. **Explore advanced MCP features** like resources and prompts
5. **Consider adding environment variables** for configuration
## License
MIT License - see LICENSE file for details.