convez.ai
MCP ServerIntegração & APIsIntermediário
Tajaddin

MCP Server Toolkit

Tajaddin/mcp-server-toolkit

Framework para construir MCP servers com testes em memória de baixa latência

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework Python reutilizável para construir servidores Model Context Protocol (MCP) para Claude, com três exemplos prontos para produção: filesystem, GitHub issues e SQLite. Inclui harness de testes em memória com latência p99 de 8.2 ms (6× menor que o alvo de 50 ms).

Instalação

$npx convez-ai Tajaddin/mcp-server-toolkit

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Construir integrações customizadas entre Claude e serviços locais ou APIs
  • Desenvolver ferramentas de acesso a arquivos, repositórios e bancos de dados
  • Testar e debugar MCP servers sem overhead de subprocessos

Veredito

Solução técnica sólida que reduz boilerplate na construção de MCP servers e oferece testes confiáveis. Os três servidores de exemplo (filesystem, GitHub, SQLite) são well-shaped e úteis; o benchmark de latência demonstra engenharia rigorosa.

README

A tradução para o português deste README ainda está na fila.

mcp-server-toolkit

Reusable framework for building Model Context Protocol (MCP) servers for Claude, plus three production-shaped example servers — filesystem-stats, github-issues, sqlite-query. In-memory test harness with p99 tool round-trip = 8.2 ms (target was 50 ms).

License Tests Python

What this is

MCP is Anthropic's standard for letting LLMs call tools running on your machine. Every MCP server starts with the same boilerplate: a FastMCP instance, a few tool decorators, a stdio entrypoint. This project bundles:

  • A thin ToolkitServer wrapper with a tool description registry + uniform ToolError error-handling pattern
  • An in-memory test harness so your tools are unit-testable via a real ClientSession — no subprocess, no JSON-over-stdio flakiness
  • Three example servers ready to install:
    • mcp-filesystem-stats — sandboxed list_directory / file_summary / find_files
    • mcp-github-issues — read-only public GitHub issue search via REST
    • mcp-sqlite-query — read-only SQLite with write-statement rejection

Hero benchmark

In-memory tool round-trip latency over 2000 iterations on a single thread (filesystem list_directory on a small dir + sqlite SELECT * FROM k).

Tool round-tripMeanp50p95p99Max
filesystem.list_directory4.02 ms3.80 ms5.81 ms8.21 ms14.49 ms
sqlite.query4.08 ms3.78 ms6.61 ms8.69 ms12.55 ms

Target: every op's p99 < 50 ms. PASS (~6× under budget).

The in-memory transport is the same ClientSession Claude would use over stdio, just connected to the server via mcp.shared.memory.create_connected_server_and_client_session. Reproduce: python bench/latency.py.

Quickstart

pip install -e ".[dev]"
import asyncio
from pathlib import Path
from mcp_server_toolkit import call_tool, in_memory_session, list_tools
from mcp_server_toolkit.servers.filesystem_stats import build_server

async def main():
    server = build_server(Path("."))
    async with in_memory_session(server) as session:
        tools = await list_tools(session)
        print([t.name for t in tools])
        # ['list_directory', 'file_summary', 'find_files']

        result = await call_tool(session, "file_summary", rel_path="README.md")
        print(result.content[0].text)

asyncio.run(main())

Or run any of the example servers as a real MCP subprocess for Claude Desktop:

pip install -e .
# In Claude Desktop's mcp settings, add:
#   "command": "mcp-filesystem-stats",
#   "args": ["--root", "/path/to/sandbox"]

Writing your own server

from mcp_server_toolkit import ToolError, ToolkitServer, register_tool

server = ToolkitServer(name="my-server", description="example")

@register_tool(server, name="echo", description="Return the input string unchanged.")
def echo(text: str) -> str:
    if not text:
        raise ToolError("text must be non-empty")
    return text

if __name__ == "__main__":
    server.run()

Tool authors:

  • Return a plain str for success.
  • Raise ToolError("...") for user-visible failures (the SDK emits isError: true).
  • Let any other exception bubble — FastMCP turns it into a generic server error.

Three example servers

filesystem-stats

Sandboxed read-only filesystem access — confined to a --root you supply at launch. Path-traversal attempts (../../etc) are rejected.

ToolArgsWhat it returns
list_directoryrel_pathTSV: name, type, size_bytes, mtime
file_summaryrel_pathsize, suffix, line count (for ≤1MB text), mode bits
find_filespattern, max_depth, limitmatching relative paths under the root

github-issues

Read-only public-repo issue search. Unauth GitHub allows 60 req/hr; set GITHUB_TOKEN to lift to 5000.

ToolArgsWhat it returns
search_issuesquery, limittop N issues matching GitHub search syntax
get_issueowner, repo, numbertitle, body, first 5 comments
list_repo_issuesowner, repo, limitopen issues newest-first

sqlite-query

Strict read-only SQLite. Only SELECT / WITH ... SELECT accepted; statement chaining via ; is rejected. Connection opens in mode=ro so even a regex bypass can't write.

ToolArgsWhat it returns
list_tables—user tables (excludes sqlite_*)
describe_tablenamecolumns + types + PK marker
querysqlTSV of up to 100 rows

Tests

pip install -e ".[dev]"
pytest -q
12 passed

Each server has an in-memory test suite that exercises:

  • tool listing (advertised tools match the registry)
  • happy-path tool calls
  • error paths (path escape, invalid table name, write statement, missing file)

Project layout

.
├── src/mcp_server_toolkit/
│   ├── __init__.py
│   ├── base.py             # ToolkitServer + ToolError + register_tool decorator
│   ├── testing.py          # in_memory_session, list_tools, call_tool
│   └── servers/
│       ├── filesystem_stats.py
│       ├── github_issues.py
│       └── sqlite_query.py
├── tests/                  # 12 pytest-asyncio cases
└── bench/
    ├── latency.py
    └── latency_results.json

Limitations

Resource and prompt support not yet wrapped. MCP has three primitive types (tools, resources, prompts). The toolkit only wraps tools right now — adding resources/prompts is straightforward but not yet done.

No multi-server orchestrator. Each example is a standalone server. A natural v0.2 would be a "router" that aggregates multiple toolkit servers under a single MCP endpoint.

github_issues is rate-limited without GITHUB_TOKEN. Heavy use during a Claude session will hit the 60 req/hr unauth limit. Set the env var to use the 5000 req/hr authenticated tier.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados