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.

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

Argumento	Equivalente
--mcp-transport {stdio,http}	MCP_TRANSPORT / server.transport
--config FICHERO	— (sustituye a ~/.aint-mcp/config.json)

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:

Variable de entorno	Clave en el JSON
MCP_ALLOW_WRITE	server.allow_write
MCP_HTTP_PORT	server.http_port
REDMINE_API_KEY	modules.redmine.api_key
SQLSERVER_ALLOWED_DATABASES	modules.sqlserver.allowed_databases
GITLAB_MAX_DIFF_CHARS	modules.gitlab.max_diff_chars

.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)

Tool	Riesgo
redmine_search_issues	read
redmine_get_issue	read
redmine_get_issue_journals	read
redmine_list_projects	read
redmine_get_project	read
redmine_create_issue	write
redmine_update_issue	write
redmine_add_note	write
redmine_add_watcher	write

SQL Server (10)

Tool	Riesgo
sqlserver_list_databases	read
sqlserver_list_schemas	read
sqlserver_list_tables	read
sqlserver_describe_table	read
sqlserver_get_foreign_keys	read
sqlserver_search_columns	read
sqlserver_analyze_schema	read
sqlserver_execute_select	read
sqlserver_get_execution_plan	read
sqlserver_execute_statement	destructive

GitLab (14)

Tool	Riesgo
gitlab_list_projects	read
gitlab_get_project	read
gitlab_search_issues	read
gitlab_get_issue	read
gitlab_list_merge_requests	read
gitlab_get_merge_request	read
gitlab_get_merge_request_changes	read
gitlab_list_pipelines	read
gitlab_get_pipeline	read
gitlab_get_file	read
gitlab_search_code	read
gitlab_create_issue	write
gitlab_update_issue	write
gitlab_add_merge_request_comment	write

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.