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

Contributing

See CONTRIBUTING.md. PRs welcome — run make all before submitting.