mcpserve-py

A Model Context Protocol (MCP) server built in Python — exposes database query tools and document resources over JSON-RPC 2.0 stdio transport, enabling AI assistants to interact with SQLite databases and markdown documents.

What is MCP?

The Model Context Protocol is an open standard for connecting AI assistants to external tools and data sources. MCP servers expose tools (functions the AI can call) and resources (data the AI can read) over a JSON-RPC 2.0 transport.

This server implements the MCP protocol from scratch using raw JSON-RPC 2.0 over stdio — no SDK dependency required.

Features

🔧 8 tools — database queries, document CRUD, search, date/time
📄 Resource providers — documents and database schemas as readable resources
🛡️ SQL injection protection — only SELECT queries allowed, with regex validation
📝 YAML frontmatter — documents stored as markdown with structured metadata
🔌 Stdio transport — line-delimited JSON-RPC 2.0 over stdin/stdout
⚡ Zero SDK dependency — hand-rolled MCP protocol implementation
✅ Well-tested — 113 tests covering protocol, tools, resources, and integration

Quick Start

# Clone and install
git clone https://github.com/devaloi/mcpserve-py.git
cd mcpserve-py
pip install -e ".[dev]"

# Run the server
python -m mcpserve_py

# Run tests
python -m pytest -v

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | MCPSERVE_DATA_DIR | data | Directory for documents and data | | MCPSERVE_DB_PATH | data/mcpserve.db | Path to SQLite database | | MCPSERVE_LOG_LEVEL | INFO | Log level (DEBUG, INFO, WARNING, ERROR) |

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mcpserve-py": {
      "command": "python",
      "args": ["-m", "mcpserve_py"],
      "env": {
        "MCPSERVE_DATA_DIR": "./data",
        "MCPSERVE_DB_PATH": "./data/mcpserve.db"
      }
    }
  }
}

Tools

| Tool | Description | Parameters | |------|-------------|------------| | query_database | Execute read-only SQL query | sql: str, params?: list | | list_tables | List all tables in database | — | | describe_table | Get table schema | table: str | | create_document | Create a markdown document | title: str, content: str, tags?: list[str] | | read_document | Read document by title | title: str | | list_documents | List all documents | tag?: str | | search_documents | Full-text search across documents | query: str | | get_datetime | Current date/time | timezone?: str |

Resources

| URI Pattern | Description | MIME Type | |-------------|-------------|-----------| | docs:///{title} | Document content | text/markdown | | db:///schema | Full database schema | text/plain | | db:///tables/{name} | Single table schema | text/plain |

Architecture

src/mcpserve_py/
├── __main__.py          # Entry point: python -m mcpserve_py
├── server.py            # MCP server: receive → dispatch → respond
├── protocol.py          # JSON-RPC 2.0 types and encoding
├── transport.py         # Stdio transport (line-delimited JSON)
├── config.py            # Pydantic settings
├── tools/
│   ├── registry.py      # Tool registry
│   ├── database.py      # SQLite tools (query, list_tables, describe)
│   ├── documents.py     # Document tools (CRUD + search)
│   └── system.py        # System tools (get_datetime)
└── resources/
    ├── provider.py      # Resource provider interface + registry
    ├── documents.py     # Document resource provider
    └── database.py      # Database schema resource provider

Design Decisions

No MCP SDK — The protocol is implemented directly using JSON-RPC 2.0 dataclasses. This demonstrates deep understanding of the protocol rather than SDK usage.
Synchronous — Stdio is inherently sequential; async adds complexity without benefit here.
Pydantic Settings — Configuration via environment variables with type validation and .env file support.
Tool registry pattern — Tools register themselves with a central registry, keeping the server dispatch clean.
Read-only SQL — Mutations are rejected via regex before reaching SQLite, preventing data corruption by AI assistants.
YAML frontmatter — Documents use the same format as static site generators (Jekyll, Hugo), making them human-readable and tool-friendly.

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
make test

# Lint
make lint

# Type check
make typecheck

# Format
make format

# All checks
make all

License

MIT

MCP Servers