Foundry Boards MCP

Servidor MCP (Model Context Protocol) que deja a Claude Code, Codex, OpenCode, Gemini y otros clientes compatibles trabajar con los tableros y las notas de Foundry: leer y mover tarjetas, gestionar épicas, sprints y etiquetas, dejar avances y verificaciones con su commit, proponer criterios y decisiones para que una persona los apruebe, y leer y escribir la documentación del Área.

An MCP server that lets AI coding agents work with Foundry's agile boards and notes.

Agente IA  ──stdio──►  foundry-boards (este MCP)  ──HTTP + JWT──►  Foundry API (/api/v1)
                                                                    (permisos por rol)

No toca el backend de Foundry: habla el mismo contrato REST que usa la aplicación web y se autentica con tu cuenta. Los permisos los decide el servidor: lo que tu cuenta no puede hacer en la web, el agente tampoco puede hacerlo.

Empezar en un minuto

Necesitas dos cosas:

• uv en el PATH. Con él no hace falta instalar Python ni el paquete: uvx lo baja, lo guarda en su caché y lo ejecuta.
• Una cuenta de Foundry. Para editar los tableros de un Área, tienes que ser colaborador o dueño de ella.

Claude Code

claude mcp add-json foundry-boards '{"type":"stdio","command":"uvx","args":["foundry-boards-mcp"]}'

Clientes que usan mcpServers (Claude Desktop, Gemini CLI, Cursor…), en su fichero de configuración. Es lo mismo que trae mcp.json.example:

{
  "mcpServers": {
    "foundry-boards": {
      "command": "uvx",
      "args": ["foundry-boards-mcp"],
      "env": { "FOUNDRY_AGENT_SOURCE": "auto" }
    }
  }
}

Codex, en ~/.codex/config.toml:

[mcp_servers.foundry-boards]
command = "uvx"
args = ["foundry-boards-mcp"]

OpenCode, en opencode.json:

{
  "mcp": {
    "foundry-boards": { "type": "local", "command": ["uvx", "foundry-boards-mcp"], "enabled": true }
  }
}

Para comprobarlo, pídele al agente «usa whoami de foundry-boards». La primera vez se abre un diálogo para entrar con tu correo y tu contraseña; si marcas «recordar», no te lo vuelve a pedir hasta que caduque la sesión (ver Autenticación).

No hay que configurar ningún backend: por omisión habla con el Foundry público. Para fijar una versión concreta, usa "args": ["foundry-boards-mcp@0.1.1"].

Qué puedes pedirle

• «Lista mis tableros y enséñame las tarjetas del de Marketing.»
• «Crea la tarea "Migrar auth a OAuth" en En progreso, prioridad alta, y asígnasela a Ana.»
• «Pasa a Hecho todas las tarjetas de En revisión que tengan sus casos de prueba en verde.»
• «Deja en la FNV-42 el avance con el commit que acabo de hacer y la verificación con los tests.»
• «Lee la nota de arquitectura del Área y dime qué decisiones siguen abiertas.»

Configuración

Todo es opcional. Se pasa como variable de entorno (el bloque env de la configuración del cliente) o, si trabajas con una copia del código, en un .env en su raíz.

Identidad del agente

Todo lo que crea el MCP (descripciones, comentarios, avances, verificaciones y cambios del historial) queda marcado como hecho por una IA, con dos datos aparte:

• agent_source: qué cliente lo hizo (claude_code, codex, opencode, gemini, other o unknown).
• agent_model: con qué modelo, por ejemplo claude-sonnet-* o gpt-5.

Foundry lo enseña como IA · Codex · gpt-5 junto a cada aporte, así que no hace falta firmar el texto. MCP no estandariza el modelo, así que conviene declararlo: con FOUNDRY_AGENT_MODEL si el proceso usa siempre el mismo, o con el argumento agent_model de cada herramienta si cambia durante la sesión. El servidor también reconoce CODEX_MODEL, CLAUDE_MODEL, ANTHROPIC_MODEL, OPENCODE_MODEL y GEMINI_MODEL.

La identidad la declara el cliente: no es una certificación y no da permisos. Lo que puede hacer el agente lo decide el rol de la cuenta.

Autenticación

No hay credenciales en ficheros ni en la configuración. La primera herramienta que necesita sesión, o la tool login, abre un diálogo en tu cliente que pide correo y contraseña, o un token.

• La contraseña no se guarda en ningún sitio: solo sirve para obtener el token.
• El token vive en memoria durante la sesión. Si marcas «recordar», se guarda en el gestor de credenciales del sistema (Windows Credential Manager, macOS Keychain o Secret Service), nunca en un fichero.
• El token dura 24 horas y no se renueva solo. Al caducar, el MCP mira primero el gestor de credenciales: si otra ventana ya renovó la sesión, la reutiliza sin preguntar. Con varias ventanas abiertas, solo la primera pide entrar.
• login cambia de cuenta; logout olvida el token, en memoria y en el sistema.

El diálogo usa elicitation de MCP. Si tu cliente no la soporta, usa FOUNDRY_TOKEN o FOUNDRY_EMAIL + FOUNDRY_PASSWORD (ver Configuración).

Herramientas

74 herramientas y 3 prompts. Cada una declara si solo lee (23), si crea o actualiza (45) o si borra (6): el cliente lo usa para saber qué puede aprobar solo y dónde pararse. Las que borran (tarjeta, nota, adjunto, columna) además preguntan antes y dicen qué se va a perder.

Sesión y panorama

Tableros y columnas

Tarjetas

Sprints

El hilo de la tarjeta

Lo que decide una persona

La IA propone y una persona acepta o descarta, en la web o con estas herramientas. Las de revisión son la decisión de una persona: un agente no debería aprobar lo que él mismo propuso.

Casos de prueba

Adjuntos

Notas

Prompts, que lanzas tú desde el cliente como un comando:

Detalles pensados para el agente

• Las columnas se nombran por nombre (sin importar tildes ni mayúsculas) o por id. Cada tablero tiene las suyas, así que se leen con get_board en vez de suponerlas: lo único estable de una columna es su category. Una tarjeta creada sin columna nace en la primera de tipo todo.
• El responsable se da por nombre o correo en los tableros de un Área. Para quitarlo: edit_task(..., assignee="").
• priority: highest, high, medium, low, lowest (también baja, media, alta). issue_type: epic, historia, tarea, bug, incidencia, subtarea.

Lo que todavía no hace

• Borrar un tablero entero: la web puede, el MCP aún no.
• Editar el flujo de estados de un tablero más allá de sus columnas.

Si te hace falta algo, abre una incidencia.

Seguridad

• Los permisos los aplica el servidor según el rol de la cuenta; el MCP no puede saltárselos.
• No se guardan contraseñas. El token solo se guarda si lo pides, y en el gestor de credenciales del sistema.
• Da a la cuenta que use el agente solo el acceso que necesite: invítala como colaboradora únicamente a las Áreas que deba tocar.

Solución de problemas

Desarrollo

git clone https://github.com/Collie-Valley/foundry-mcp.git
cd foundry-mcp
uv sync                 # crea .venv con las dependencias y el grupo dev
uv run pytest -q        # las pruebas
uvx ruff check .        # el estilo, con la configuración de pyproject.toml
uv run mypy             # los tipos, en modo estricto (también desde pyproject.toml)

En Windows, .\run.ps1 hace el uv sync y comprueba que el servidor carga y lista sus tools.

Para que tu cliente use tu copia en vez del paquete publicado, lánzalo con uv run apuntando a la carpeta (ruta absoluta):

{
  "mcpServers": {
    "foundry-boards": {
      "command": "uv",
      "args": ["run", "--directory", "/ruta/a/foundry-mcp", "python", "run_server.py"]
    }
  }
}

Con una copia del código, el MCP lee el .env de la raíz del repositorio: .env.example dice qué admite. Ese .env gana sobre el bloque env del cliente, y nunca se versiona.

El estilo se comprueba con ruff check y nada más: el formateador automático no se usa en este proyecto. Los tipos, con mypy --strict sobre el paquete (no sobre las pruebas). Las pruebas cubren el cliente HTTP y los ayudantes del servidor con dobles, sin hablar con un Foundry real.

Publicar una versión

Se publica desde una etiqueta, nunca a mano. Una versión subida a PyPI no se puede reemplazar.

1. Sube version en pyproject.toml y haz merge a main.
2. git tag v<versión> && git push origin v<versión>

El workflow publish.yml comprueba que la etiqueta coincide con la versión, pasa las pruebas, construye el paquete y lo sube a PyPI por trusted publishing (OIDC), sin ningún token guardado.

Licencia

MIT © Collie Valley.