NotERP MCP

Servidor MCP (Model Context Protocol) en Python con tools para consultar endpoints del sitio NotERP.

Stack

• mcp (SDK oficial de Anthropic) con MCPServer
• httpx para peticiones HTTP
• Ejecutado con uv

Requisitos

• uv (con gestor de Python incluido)

Configuración

Copia .env.example a .env y configura las variables:

Ejecución

# stdio (recomendado para opencode, Claude Desktop, etc.)
uv run noterp-mcp

# HTTP (Streamable HTTP)
TRANSPORT=streamable-http uv run noterp-mcp

# SSE
TRANSPORT=sse uv run noterp-mcp

También funciona con uv run python -m noterp_mcp.

Configuración en un cliente MCP

Ejemplo para opencode (opencode.json):

{
  "mcp": {
    "noterp": {
      "type": "local",
      "command": ["uv", "run", "noterp-mcp"],
      "environment": {
        "BASE_URL": "https://tu-noterp.example.com",
        "TOKEN": "tu-token",
        "SUBSCRIPTION_TOKEN": "tu-token-de-suscripcion"
      }
    }
  }
}

Agregar una tool nueva

1. Crea un archivo en src/noterp_mcp/tools/ (ej. noterp_usuarios.py).

2. Define register(mcp) dentro:

   from mcp.server import MCPServer
   from noterp_mcp.client import request
   
   def register(mcp: MCPServer) -> None:
       @mcp.tool()
       def listar_usuarios(activo: bool = True) -> str:
           """Lista usuarios del sitio NotERP."""
           return request("GET", "/api/usuarios", params={"activo": activo})
   

3. Regístralo en src/noterp_mcp/server.py:

   from noterp_mcp.tools import noterp_generic, noterp_usuarios
   
   TOOL_MODULES = [noterp_generic, noterp_usuarios]
   

Autenticación

El TOKEN viaja como parte de la ruta del endpoint. En el path se usa el placeholder {TOKEN} (ej. /service/serviceListaEmpleados.php/listaEmpleados/{TOKEN}) y el cliente lo sustituye por el valor URL-encoded de TOKEN. Si el path incluye {TOKEN} y no hay token configurado, la tool devuelve un error claro. Los headers de auth se gestionan en auth_headers de src/noterp_mcp/client.py.

Validación de suscripción

Antes de ejecutar cualquier tool se consulta el servicio de póliza (GET {SUBSCRIPTION_URL}/{SUBSCRIPTION_TOKEN}). Se considera válida cuando la respuesta trae response == "OK" y vigente is True; en cualquier otro caso (NOK, JSON inválido, error HTTP o de red) la tool se bloquea (fail-closed). Un resultado válido se cachea 60 segundos. SUBSCRIPTION_TOKEN es obligatorio: sin él el servidor no arranca.

Autenticación Bearer en web

Con TRANSPORT=streamable-http o TRANSPORT=sse el servidor exige el header Authorization: Bearer <token> en cada petición; sin token válido responde 401. Los tokens se configuran en MCP_BEARER_TOKEN (varios separados por comas para rotar con solapamiento). Si no se configura, el servidor no arranca. En stdio no se pide token.

Tools