# 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`](https://py.sdk.modelcontextprotocol.io/) 2.x para
Python. Funciona con Claude Code, Codex y cualquier otro cliente MCP.

## Instalación

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
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

```bash
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`:

```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:

```json
"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`.

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

```json
"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

```bash
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

```text
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.