legal-mcp-template

IA Lab · Facultad de Derecho — Universidad de Palermo (UP)

Una herramienta para que estudiantes de Derecho construyan su propio conector MCP legal y aprendan IA construyéndola, no consumiéndola.

Un conector MCP (Model Context Protocol) es un programa que le da herramientas a un asistente de IA como Claude. Este template te deja construir el tuyo: un servidor que responde consultas jurídicas y que, por construcción, no puede afirmar nada del derecho sin citar la fuente. Si una respuesta no tiene fundamento declarado, el programa se rompe a propósito.

Esa disciplina —el grounding— es justamente lo que reduce el riesgo de alucinación: el asistente no puede "inventar" una norma o un fallo, porque toda afirmación viaja con su cita o no sale. Es el deber de control que los tribunales ya están exigiendo, convertido en el comportamiento por defecto.

No hace falta saber programar. Vas a tocar dos archivos nada más: my_tools.py (tus respuestas) y sources.yaml (tus fuentes).

Qué certifica el check (y qué no). Cuando make check da verde, eso significa "toda afirmación tiene una fuente declarada". No significa que el contenido jurídico sea correcto: eso lo revisa un humano. El verde es sobre la disciplina de citar, no sobre el derecho.

---

Instalación

Necesitás Python 3.11 o más nuevo. Elegí tu sistema operativo.

La forma más fácil: GitHub Codespaces (sin instalar nada)

Desde GitHub: botón Code → Codespaces → Create codespace. El entorno se arma solo y corre make check al final. Si lo viste terminar en verde, ya está todo listo y podés saltar a Construí tu propio conector.

macOS

1. Python. Verificá que tengas 3.11+:

   python3 --version
   

   Si no lo tenés, instalalo desde python.org o con Homebrew: brew install python.

2. Herramientas de compilación (para make). Si nunca las instalaste:

   xcode-select --install
   

3. Descargá el proyecto y entrá a la carpeta:

   git clone <URL-del-repo> legal-mcp-template
   cd legal-mcp-template
   

4. Creá un entorno virtual e instalá (en Mac conviene siempre usar un venv):

   python3 -m venv .venv
   source .venv/bin/activate
   make install
   

5. Comprobá que todo funciona:

   make check
   

   Tiene que terminar en verde.

Cada vez que vuelvas a trabajar, reactivá el entorno con source .venv/bin/activate desde la carpeta del proyecto.

Windows

1. Python. Instalalo desde python.org y, en el instalador, tildá "Add Python to PATH". Verificá en PowerShell:

   py --version
   

2. Descargá el proyecto y entrá a la carpeta:

   git clone <URL-del-repo> legal-mcp-template
   cd legal-mcp-template
   

3. Creá un entorno virtual e instalá:

   py -m venv .venv
   .venv\Scripts\activate
   pip install -e ".[dev]"
   

4. Comprobá que todo funciona. Windows no trae make, así que corré los tres pasos a mano (es exactamente lo que hace make check):

   python -m ruff check .
   python -m legalmcp sources.yaml examples\consumidor\sources.yaml
   python -m pytest
   

   Los tres tienen que pasar.

¿Querés usar make en Windows? Podés instalarlo con Scoop (scoop install make) o Chocolatey (choco install make). No es obligatorio.

---

Probá el ejemplo

El proyecto trae un conector completo y funcionando sobre derechos del consumidor (Ley 24.240). Con el entorno activado:

cd examples/consumidor
python -m legalmcp.server

(Esto levanta el servidor; cortalo con Ctrl+C.) Abrí examples/consumidor/my_tools.py: son dos tools cortas, comentadas línea por línea. Fijate cómo una de ellas, cuando la consulta cae fuera de su tema, devuelve not_found=True en vez de inventar una respuesta. Ese es el patrón.

Conectarlo a Claude Desktop

Para usar tu conector dentro de la app Claude Desktop, editá su archivo de configuración:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

El archivo debe contener solo la clave mcpServers en el nivel superior. Reemplazá /ruta/a/legal-mcp-template por la ruta real donde clonaste el proyecto.

macOS:

{
  "mcpServers": {
    "consumidor": {
      "command": "/bin/sh",
      "args": [
        "-c",
        "cd /ruta/a/legal-mcp-template/examples/consumidor && exec /ruta/a/legal-mcp-template/.venv/bin/legal-mcp"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "consumidor": {
      "command": "cmd",
      "args": [
        "/c",
        "cd /d C:\\ruta\\a\\legal-mcp-template\\examples\\consumidor && C:\\ruta\\a\\legal-mcp-template\\.venv\\Scripts\\legal-mcp.exe"
      ]
    }
  }
}

Guardá, cerrá Claude Desktop por completo y volvé a abrirlo. Vas a ver las tools del conector disponibles. Probá: "¿qué garantía tengo si compro algo y sale fallado?" — debería citarte el artículo correspondiente.

El cd del comando es necesario porque Claude lanza el servidor desde una carpeta cualquiera, y el servidor busca my_tools.py y sources.yaml en el directorio actual.

---

Construí tu propio conector

1. Copiá una tool a tu my_tools.py y cambiale el texto

Abrí el my_tools.py de la raíz. Tiene una tool de ejemplo comentada. Descomentala (sacale los #), poné tu propia respuesta jurídica en answer y elegí un id de fuente para citar. Guiate por el ejemplo de consumidor.

La regla que no podés saltear: si escribís una respuesta en answer, tenés que citar al menos una fuente con src("..."). Si no encontrás fundamento, devolvé GroundedResponse(not_found=True).

2. Declará tu fuente en sources.yaml

src("mi_fuente") solo funciona si mi_fuente está declarada en sources.yaml. Abrí sources.yaml, copiá el bloque de ejemplo y completá la cita. Si tenés la URL oficial verificada, ponela; si no, dejala vacía y anotala como pendiente en SOURCES.md. Nunca inventes una URL.

3. make check en verde

make check

(En Windows, los tres comandos de la sección de instalación.) Esto corre el linter, la validación de tus fuentes y los tests. Si citaste una fuente que no declaraste, o escribiste una respuesta sin fuente, queda en rojo. Arreglalo hasta que dé verde.

4. Completá el manifiesto

Abrí mcp-manifest.yaml y poné tu nombre, tu dominio y la lista de ids de fuentes que usás. Dejá review_status: borrador hasta que un humano revise el contenido jurídico.

¡Listo! Tenés un conector MCP legal con grounding garantizado.

5. Sumá más tools (así enriquecés el contexto del MCP)

Cuantas más tools tenga tu conector, más temas puede responder con fundamento el asistente. Cada tool nueva es como agregarle a Claude un "ayudante" experto en un punto puntual del derecho. Agregar una es repetir la misma receta, sin tocar nada raro:

1. Copiá una tool que ya funcione (la tuya o una del ejemplo) y pegala más abajo en my_tools.py, debajo de la anterior. No borres las que ya tenés.
2. Cambiale el nombre de la función (la línea def ...) por uno nuevo y distinto. Dos tools no pueden llamarse igual. Usá un nombre claro, en minúsculas y con guiones bajos: def licencia_por_maternidad(consulta):.
3. Reescribí el docstring (el texto entre """...""" justo debajo del def): explicá en una frase qué responde. Eso es lo que Claude lee para saber cuándo usarla.
4. Cambiá el answer por tu respuesta jurídica, en lenguaje claro.
5. Citá la fuente: poné en sources=[src("...")] el id de la norma, y declará esa norma en sources.yaml (igual que en el paso 2 de arriba). Si no tenés fundamento para un caso, devolvé GroundedResponse(not_found=True).
6. Corré make check. Si te olvidaste de declarar una fuente, o escribiste una respuesta sin cita, el check te lo marca en rojo y te dice qué arreglar. Verde = tu tool nueva ya cumple el contrato y suma al conector.

Repetí esto cuantas veces quieras. No hay un paso 7: no tenés que "registrar" la tool en ningún otro lado ni avisarle al servidor. Con solo escribirla con @grounded_tool arriba, ya queda disponible la próxima vez que levantes el conector.

La regla de siempre, también acá: una tool sin fuente no entra. Si dudás de dónde sale una afirmación, no la afirmes: usá not_found=True y, si hace falta, sugerí consultar la fuente oficial o a un humano.

---

Cómo está armado (para curiosos)

.
├── my_tools.py          ← TU código (lo editás vos)
├── sources.yaml         ← TUS fuentes (las declarás vos)
├── SOURCES.md           ← de dónde sale cada fuente
├── mcp-manifest.yaml    ← metadatos de tu conector
├── legalmcp/            ← el harness (NO se toca)
│   ├── contract.py      ← GroundedResponse, Source, @grounded_tool (fail-closed)
│   ├── sources.py       ← carga/valida sources.yaml; src(id) resuelve o se rompe
│   └── server.py        ← arma el server FastMCP y registra tus tools
├── tests/               ← prueban que el contrato sirve
└── examples/consumidor/ ← ejemplo completo y forkeable

El harness es fino y se apoya directo en el SDK oficial de MCP (FastMCP): no hay lenguaje propio ni compilador que se pueda pudrir cuando el SDK evolucione.

Comandos

Comando	Qué hace
make install	Instala el harness y las dependencias
make dev	Levanta tu servidor MCP
make test	Corre los tests
make check	Linter + validación de fuentes + tests (lo que mira CI)

---

Seguridad

¿Encontraste una vulnerabilidad? Por favor reportala en privado antes de divulgarla. Mirá SECURITY.md — el contacto es gbarosio@gmail.com.

Autores

• Guido Barosio
• Juan Cruz Romano
• Hernán Quadri
• Aníbal Ramírez

Licencia

Distribuido bajo la licencia BSD 3-Clause. Ver LICENSE.