aint-mcp

Servidor MCP modular que agrupa tres integraciones internas en un único proceso: Redmine, SQL Server y GitLab. Pensado para el flujo habitual de investigar una incidencia: localizarla en Redmine, comprobar los datos o la estructura implicada en SQL Server y revisar la merge request correspondiente en GitLab.

Construido sobre el SDK oficial mcp 2.x para Python. Funciona con Claude Code, Codex y cualquier otro cliente MCP.

Instalación

pip install git+https://github.com/AINTDevLab/aint-mcp.git

Eso deja disponible el comando aint-mcp. Requiere Python 3.13+.

Como es una herramienta de línea de comandos y no una librería, lo más limpio es instalarla en su propio entorno aislado:

uv tool install git+https://github.com/AINTDevLab/aint-mcp.git
# o, si prefieres pipx
pipx install git+https://github.com/AINTDevLab/aint-mcp.git

Fijar una versión o una rama concretas, y actualizar:

pip install git+https://github.com/AINTDevLab/aint-mcp.git@v0.1.0
pip install git+https://github.com/AINTDevLab/aint-mcp.git@main

pip install --upgrade --force-reinstall git+https://github.com/AINTDevLab/aint-mcp.git
uv tool upgrade aint-mcp

Después, crea el fichero de configuración:

mkdir -p ~/.aint-mcp
curl -o ~/.aint-mcp/config.json \
  https://raw.githubusercontent.com/AINTDevLab/aint-mcp/main/config.example.json

El módulo de SQL Server necesita un driver ODBC (ODBC Driver 17 for SQL Server o superior). Si no lo tienes, quita sqlserver de modules y el resto funciona igual: los módulos se importan de forma perezosa y pyodbc ni siquiera llega a cargarse.

Desde el código fuente

git clone https://github.com/AINTDevLab/aint-mcp.git
cd aint-mcp
uv sync

Con el proyecto clonado, todos los comandos van precedidos de uv run.

Related MCP server: GitLab MCP Server

Uso

aint-mcp                            # stdio, el modo normal para clientes MCP
aint-mcp --mcp-transport http       # Streamable HTTP en 127.0.0.1:8000/mcp
aint-mcp --config ./config.json     # otro fichero de configuración
aint-mcp --help

Para darlo de alta en Claude Code, copia .mcp.json.example a .mcp.json:

{
  "mcpServers": {
    "aint-mcp": {
      "command": "aint-mcp",
      "args": [],
      "env": {}
    }
  }
}

Con la configuración en ~/.aint-mcp/config.json no hace falta nada más. Si quieres otro fichero, añade "--config", "C:/ruta/config.json" a args; cualquier variable que pongas en "env" sobrescribe al fichero:

"env": { "MCP_ALLOW_WRITE": "true", "GITLAB_TOKEN": "..." }

Si lo has instalado con uv tool o pipx y el cliente MCP no encuentra el comando, usa la ruta absoluta que devuelve which aint-mcp (o where aint-mcp en Windows): algunos clientes no heredan el PATH de tu shell.

Configuración

Hay tres formas de configurar el servidor y se pueden combinar. De mayor a menor prioridad:

1. Argumentos de línea de comandos — --mcp-transport

2. Variables de entorno — MCP_ALLOW_WRITE, REDMINE_API_KEY, ...

3. Fichero .env del directorio actual

4. Fichero de configuración JSON — ~/.aint-mcp/config.json, o el que indique --config

5. Valores por defecto

Lo habitual es dejar lo estable en el fichero JSON y sobrescribir puntualmente con el entorno o un argumento: probar una ejecución con --mcp-transport http sin tocar nada, o inyectar un token distinto desde el .mcp.json de un cliente concreto.

El fichero JSON

config.example.json es una plantilla completa y comentada por su propia estructura. Copia el que quieras usar a ~/.aint-mcp/config.json.

{
  "server": {
    "modules": ["redmine", "sqlserver", "gitlab"],
    "allow_write": false,
    "allow_destructive": false,
    "transport": "stdio",
    "http_host": "127.0.0.1",
    "http_port": 8000,
    "http_path": "/mcp",
    "log_level": "INFO"
  },
  "modules": {
    "redmine": {
      "base_url": "https://redmine.example.es",
      "api_key": "..."
    },
    "sqlserver": {
      "connection_string": "DRIVER={ODBC Driver 17 for SQL Server};SERVER=srv,1433;DATABASE=CEN;UID=lector;PWD=...;TrustServerCertificate=yes",
      "allowed_databases": ["CEN", "GEN"],
      "allowed_procedures": [],
      "query_timeout": 15,
      "max_rows": 500,
      "allow_dml": false
    },
    "gitlab": {
      "base_url": "https://gitlab.example.es",
      "token": "...",
      "max_diff_chars": 20000
    }
  }
}

Sólo hay dos secciones, server y modules. Las claves de cada sección son el nombre de su variable de entorno sin el prefijo, así que la equivalencia es directa:

.env.example lista todas las opciones disponibles con su valor por defecto.

Un par de decisiones sobre el manejo de errores, para que no haya sorpresas:

• Si --config apunta a un fichero que no existe, el servidor aborta con código 2. Arrancar en silencio con la configuración por defecto sería peor que fallar.

• Que falte el fichero del perfil no es un error: simplemente no hay nada que cargar.

• Una sección o un módulo mal escritos ("servidor", "gitlba") abortan el arranque. Ignorarlos en silencio cuesta horas de depuración.

• Una clave desconocida dentro de una sección se ignora con un aviso en el log, para no romper con ficheros de versiones futuras.

Catálogo de tools

33 tools, con prefijo por módulo. Los nombres usan guion bajo porque el protocolo exige el patrón ^[a-zA-Z0-9_-]{1,64}$: los puntos no son válidos.

Redmine (9)

SQL Server (10)

GitLab (14)

Seguridad

Cada tool tiene un nivel de riesgo — read, write o destructive — y si su nivel no está permitido, la tool no llega a registrarse. El modelo no ve una herramienta que no puede usar, así que no gasta tokens intentándolo ni improvisa alternativas.

"server": {
  "allow_write": false,        // por defecto, sólo lectura
  "allow_destructive": false
}

El nivel también se traduce a ToolAnnotations (read_only_hint, destructive_hint) para que el cliente pueda pedir confirmación.

SQL Server

El control real es el usuario de base de datos de sólo lectura. Todo lo demás es defensa en profundidad:

• Análisis con sqlglot en dialecto tsql, no con expresiones regulares: los regex sobre SQL se saltan con comentarios intercalados o espacios raros.

• Una sola sentencia por llamada. Bloquea el clásico SELECT 1; DROP TABLE x.

• Raíz obligatoriamente SELECT, WITH ... SELECT o unión de selects.

• Rechazo de INSERT, UPDATE, DELETE, MERGE, DROP, ALTER, CREATE, TRUNCATE, GRANT, USE, SET y EXEC.

• Rechazo de SELECT ... INTO: es una escritura cuya raíz sigue siendo un SELECT.

• Rechazo de OPENROWSET, OPENQUERY, OPENDATASOURCE y xp_cmdshell.

• Lista blanca de bases de datos: sin ella sólo se admiten referencias sin cualificar.

• Límite de filas y timeout configurables; el recorte se marca con truncated: true.

• Registro en el log de cada consulta ejecutada y su veredicto.

sqlserver_execute_statement necesita dos interruptores (MCP_ALLOW_DESTRUCTIVE y SQLSERVER_ALLOW_DML) más un confirm=true en cada llamada, y sigue sin permitir DDL.

Desarrollo

uv run pytest       # 101 tests
uv run ruff check .
uv run mypy

La batería más importante es tests/test_sql_guard.py: cada intento de bypass que se nos ocurra debería quedar escrito ahí.

Estructura

src/aint_mcp/
├─ __main__.py          argumentos de línea de comandos y arranque
├─ server.py            create_server(): registra los módulos activos
├─ core/
│  ├─ config.py         pydantic-settings, un bloque por integración
│  ├─ config_file.py    carga y validación de config.json
│  ├─ permissions.py    RiskLevel + ToolRegistrar (filtrado en el registro)
│  ├─ registry.py       activación e importación perezosa de módulos
│  ├─ http.py           cliente httpx con reintentos y errores tipados
│  ├─ errors.py         errores de negocio → ToolError legible
│  └─ logging.py        siempre a stderr; stdout es del protocolo
├─ modules/
│  ├─ redmine/   client.py, schemas.py, tools/, register.py
│  ├─ sqlserver/ client.py, guard.py, metadata.py, schemas.py, tools/, register.py
│  └─ gitlab/    client.py, schemas.py, tools/, register.py
└─ shared/       pagination.py, text.py

Añadir una tool son dos pasos: un fichero en modules/<módulo>/tools/ con una función register(reg, client) decorada con @reg.tool(...), y una línea en el _TOOL_MODULES del register.py del módulo.

Las tools devuelven modelos Pydantic reducidos, no el JSON crudo de la API: el SDK genera el structuredContent y el esquema de salida a partir del tipo de retorno, y así no se queman miles de tokens en campos que nadie mira.

Si algún día SQL Server necesita más aislamiento, se puede separar en un MCP propio sin cambiar ni un nombre ni un contrato de tool.