mcpforge

Despliega un servidor MCP en 5 líneas de Python.

Before                              After
──────                              ─────
~200 lines of                       @serve
JSON-RPC stdio                      class MarketTools:
boilerplate, schema                     @tool
generation, error                       def latest_price(self, symbol: str) -> float: ...
handling, lifecycle                     @tool
management.                             def search(self, query: str) -> list[dict]: ...

                                    $ python -m mcpforge run market:MarketTools
                                    ✓ MCP server running on stdio

Por qué mcpforge

El Model Context Protocol (MCP) es el estándar abierto que utilizan Claude, Cursor y un ecosistema en expansión de herramientas de IA para llamar a funciones externas. Es potente, pero escribir un servidor actualmente es una pesadilla.

Escribes el mismo marco JSON-RPC, generación de esquemas, bucle de despacho y manejo de errores en cada proyecto. mcpforge elimina todo eso. Anota tu clase. Usa sugerencias de tipo en tus métodos. Listo.

from mcpforge import serve, tool

@serve(name="market_tools", version="0.1.0")
class MarketTools:
    """Market data tools for AI agents."""

    @tool(description="Get the latest price for a symbol")
    def latest_price(self, symbol: str) -> float:
        return fetch_price(symbol)

    @tool
    def search(self, query: str, limit: int = 10) -> list[dict]:
        """Search ticker symbols matching `query`."""
        return run_search(query, limit)

Eso es un servidor MCP completo y compatible con las especificaciones. Las sugerencias de tipo se convierten en JSON Schema. Los docstrings se convierten en descripciones de herramientas. Los retornos se serializan automáticamente.

Inicio rápido en 60 segundos

pip install mcpforge

# hello.py
from mcpforge import serve, tool

@serve(name="hello", version="0.1.0")
class HelloTools:
    @tool
    def greet(self, name: str = "world") -> str:
        """Say hello to someone."""
        return f"Hello, {name}!"

python -m mcpforge run hello:HelloTools

Ahora tienes un servidor MCP funcional que habla JSON-RPC 2.0 a través de stdio.

Cómo funciona

1. @serve etiqueta una clase como un servidor MCP (nombre, versión, capacidades).

2. @tool registra métodos como herramientas MCP.

3. @resource(uri=...) registra métodos como recursos MCP.

4. mcpforge introspecciona la firma de cada método y produce un JSON Schema: primitivos, list[T], dict[str, T], Literal[...], Optional[T], dataclasses y modelos de Pydantic, todo funciona simplemente.

5. python -m mcpforge run mod:Class inicia el bucle stdio, maneja initialize / tools/list / tools/call / resources/list / resources/read, y reporta errores JSON-RPC con los códigos adecuados.

Sin SDK de MCP externo. Solo json de la biblioteca estándar + pydantic para las bondades del esquema.

Servidores integrados

Dos servidores con todo incluido que puedes implementar hoy mismo:

# Filesystem tools (sandboxed to a root directory)
python -m mcpforge run mcpforge.builtin.filesystem:FilesystemTools

# HTTP fetch tools
python -m mcpforge run mcpforge.builtin.http:HttpTools

FilesystemTools expone list_dir, read_file, search, con entorno aislado y comprobaciones de recorrido de rutas. HttpTools expone fetch_url con límites de tamaño.

Conectar a Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "market": {
      "command": "python",
      "args": ["-m", "mcpforge", "run", "market:MarketTools"],
      "cwd": "/path/to/your/project"
    }
  }
}

Reinicia Claude Desktop. Tus herramientas aparecerán en la conversación.

Conectar a Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "market": {
      "command": "python",
      "args": ["-m", "mcpforge", "run", "market:MarketTools"]
    }
  }
}

Comparación

Inspeccionar el formato de red

python -m mcpforge inspect market:MarketTools

Imprime la carga útil exacta de tools/list que verán tus clientes.

Hoja de ruta

• [x] Herramientas (call, list)

• [x] Recursos (read, list)

• [x] Type-hint -> JSON Schema (Pydantic v2, dataclasses, Literal, Optional)

• [x] Servidores de sistema de archivos y http integrados

• [ ] Suscripciones a recursos

• [ ] Capacidad de prompts

• [ ] Capacidad de muestreo

• [ ] Transporte WebSocket / HTTP-SSE (extra opcional [http])

• [ ] Herramientas asíncronas (async def)

• [ ] Ganchos de rastreo OTel

Licencia

MIT — ver LICENSE.

Autor: thechifura. Hermano de quantflow y strategos.