custom-mcp-server

MCP Server

Model Context Protocol Server for LLM Tool Integration. This server provides a standardized way to handle tool connections for LLM-powered applications.

Setup

Prerequisites

• Python 3.12 or higher
• Docker (optional)

Local Development Setup

1. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

uv pip install -e .

3. Create a .env file:

SECRET_KEY=your-secure-secret-key
SEARCH_API_KEY=your-search-api-key  # Optional
SEARCH_ENGINE_ID=your-search-engine-id  # Optional

4. Run the server:

python -m mcp_server.server

Docker Setup

1. Build and run with Docker Compose:

docker-compose up --build

The server will be available at http://localhost:8000

API Documentation

Authentication

All endpoints except the token endpoint require authentication using a JWT token.

Get Token

curl -X POST http://localhost:8000/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=testuser&password=testpass"

Response:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "token_type": "bearer"
}

Tools API

List Available Tools

curl http://localhost:8000/list_tools \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Response:

{
    "tools": [
        {
            "name": "web_search",
            "description": "Search the web for information",
            "type": "web_search",
            "parameters": [
                {
                    "name": "query",
                    "type": "string",
                    "description": "The search query to find information on the web",
                    "required": true
                },
                {
                    "name": "num_results",
                    "type": "integer",
                    "description": "Number of results to return",
                    "required": false,
                    "default": 5
                }
            ]
        }
    ]
}

Execute Tool

curl -X POST http://localhost:8000/execute_tool \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "web_search",
    "parameters": {
        "query": "example search query",
        "num_results": 3
    }
}'

Response:

{
    "status": "success",
    "result": {
        "query": "example search query",
        "results": [
            {
                "title": "Example Result",
                "snippet": "This is a placeholder for actual search results",
                "url": "https://example.com"
            }
        ]
    },
    "error": null
}

Register New Tool

curl -X POST http://localhost:8000/register_tool \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "custom_tool",
    "description": "A custom tool example",
    "type": "function",
    "parameters": [
        {
            "name": "param1",
            "type": "string",
            "description": "First parameter",
            "required": true
        },
        {
            "name": "param2",
            "type": "integer",
            "description": "Second parameter",
            "required": false,
            "default": 0
        }
    ]
}'

Response:

{
    "status": "success",
    "message": "Tool custom_tool registered successfully"
}

Development

Project Structure

mcp-server/
├── src/
│   └── mcp_server/
│       ├── __init__.py
│       └── server.py
├── main.py
├── pyproject.toml
├── Dockerfile
└── docker-compose.yml

Adding New Tools

To add a new tool:

1. Define the tool in the server code
2. Register it using the register_tool function
3. Implement the tool's logic in the execute_tool endpoint

Environment Variables

• SECRET_KEY: Secret key for JWT token generation
• SEARCH_API_KEY: API key for web search (optional)
• SEARCH_ENGINE_ID: Search engine ID for web search (optional)
• HOST: Server host (default: 0.0.0.0)
• PORT: Server port (default: 8000)

Security Notes

• The default user credentials (testuser/testpass) should be changed in production
• Use a strong SECRET_KEY in production
• Implement proper user management and database storage
• Add rate limiting for production use
• Use HTTPS in production

License

MIT