MCP Stark Brain (Payments)

Servidor MCP local que ayuda al equipo de Payments en el trabajo diario:

• Consultar el patrón arquitectónico utilizado por los microservicios de Python.

• Buscar las especificaciones de los microservicios (objetivo y responsabilidad de cada servicio).

• Comprender los flujos de procesamiento de pagos.

• Hacer el triaje e investigar los tickets de Customer Success (CS) combinando la búsqueda en la documentación con el análisis de GCP (Datastore + Cloud Logging / Log Explorer).

• Llamar a las APIs de Stark Bank en development (por defecto) o sandbox (solo cuando se solicite explícitamente) usando tus credenciales ECDSA de Proyecto.

Realiza RAG sobre la documentación en starkbank/alexandria, firma las solicitudes a la API de Stark Bank con tu clave privada y ejecuta consultas de GCP usando tu propia identidad de gcloud (ADC).

1. Cómo funciona

IDE / LLM  --stdio-->  MCP server
                         |-- Docs (RAG): fetch alexandria via GitHub PAT -> local vector index
                         |-- Stark Bank API: ECDSA-signed HTTP to development (default) / sandbox
                         |-- GCP: Datastore + Cloud Logging via your gcloud ADC (project per call)

• La documentación es remota por defecto (no se mantiene un clon de git). El servidor descarga el tarball del repositorio a través de la API de GitHub (una sola solicitud para todo el contenido) para crear un índice local de embeddings. Solo el índice vectorial se almacena en caché localmente.

• Consciente del límite de tasa. Cuando el presupuesto de GitHub se agota, el servidor sugiere clonar el repositorio y cambiar al modo local (ver sección 10).

• La API de Stark Bank usa development por defecto (https://development.api.starkbank.com). Sandbox solo se usa cuando se llama a una herramienta con environment="sandbox" después de una solicitud explícita del usuario. Nunca se permite producción.

• El proyecto de GCP se pasa en cada llamada. No hay una variable de entorno de proyecto fija: cada consulta recibe un project explícito, para que puedas saltar entre proyectos de microservicios en la misma sesión sin tocar tu gcloud config global.

• No hay claves de cuenta de servicio para GCP. El acceso a GCP usa tus credenciales ADC personales, lo que conserva los permisos y las pistas de auditoría por usuario.

2. Requisitos previos

• Python 3.12 (necesario para compilar/instalar el paquete). chromadb y fastembed (a través de onnxruntime) aún no distribuyen de forma fiable ruedas precompiladas para intérpretes más nuevos, por lo que el proyecto fija requires-python = ">=3.11,<3.13" y todos los comandos siguientes apuntan explícitamente a 3.12 — no sustituyas el python3 predeterminado de tu sistema sin comprobar antes su versión.

• uv (recomendado) o pipx para instalar el paquete.

• Google Cloud SDK (gcloud).

Comprueba/instala la versión fijada de Python con uv (no afecta al Python de tu sistema):

uv python install 3.12

3. Genera tu GitHub PAT

Cada desarrollador genera su propio PAT (nunca compartido, nunca comprometido). alexandria es privado y pertenece a la organización starkbank, por lo que el tipo de token que funciona depende de la política de tokens de la organización: lee ambas opciones antes de elegir una.

Opción A: PAT de grano fino (prueba esto primero)

1. GitHub -> Configuración -> Configuración de desarrollador -> Tokens de grano fino -> Generar nuevo token.

2. Propietario del recurso: starkbank.

3. Acceso al repositorio: Solo repositorios seleccionados -> starkbank/alexandria.

4. Permisos: Permisos del repositorio -> Contents: Read-only.

5. Genera y copia el token (lo establecerás como variable de entorno en tu mcp.json).

6. Comprueba su estado en https://github.com/settings/personal-access-tokens. Si la organización exige aprobación, aparecerá como Pending y dará 404 en cada solicitud hasta que se apruebe. Pide a un propietario de la organización starkbank que lo apruebe en Configuración -> Tokens de acceso personal -> Solicitudes pendientes de la organización, o pasa a la Opción B.

Opción B: PAT clásico (alternativa si la organización no aprueba los tokens de grano fino)

Los PAT clásicos no están sujetos al paso de aprobación de la organización anterior, por lo que son la vía más rápida si tu organización restringe los tokens de grano fino:

1. GitHub -> Configuración -> Configuración de desarrollador -> Tokens (clásico) -> Generar nuevo token.

2. Ámbito: repo (los tokens clásicos no tienen un ámbito solo de contenido para repositorios privados).

3. Si la organización starkbank exige SSO, haz clic en Configure SSO junto al token recién creado y Autorízalo para starkbank — un token no autorizado dará 404 en los recursos de starkbank exactamente igual que uno de grano fino no aprobado.

En cualquier caso, una vez instalado, ejecuta la herramienta diagnose_github_access (ver sección 8) para confirmar que el token realmente funciona antes de depender de él.

4. Autentícate con GCP (ADC)

gcloud auth login
gcloud auth application-default login

No necesitas configurar un proyecto aquí: el MCP recibe project en cada llamada de herramienta GCP. Usa analyze_ticket / resolve_project para obtener sugerencias de proyectos.

5. Credenciales de la API de Stark Bank (ECDSA)

Las llamadas a la API se autentican con ECDSA (secp256k1), no con claves API estáticas. Consulta la documentación oficial: Autenticación.

1. Genera un par de claves (si aún no lo has hecho) y registra solo la clave pública en Web Banking (Integraciones → Proyecto) para el entorno de desarrollo.

2. Mantén el PEM de la clave privada en tu máquina: nunca lo hagas commit y nunca pongas la clave pública dentro de este repositorio (el MCP no necesita la clave pública para firmar solicitudes).

3. Anota el ID de Proyecto que se muestra en Web Banking después de crear/registrar el Proyecto.

4. Apunta el MCP al PEM y al ID de Proyecto mediante variables de entorno (ver paso 6 / sección 11).

Ubicación sugerida para la clave privada (fuera del repositorio):

mkdir -p ~/.config/mcp-stark-brain
chmod 700 ~/.config/mcp-stark-brain
# copy your privateKey.pem there, then:
chmod 600 ~/.config/mcp-stark-brain/privateKey.pem

URLs base predeterminadas:

6. Compilar el paquete (wheel)

Desde la raíz del repositorio, fija siempre el intérprete explícitamente a Python 3.12 — no ejecutes un simple uv build y confíes en el Python que esté primero en tu PATH:

rm -rf dist  # avoid mixing wheels from a previous version/build
uv build --python 3.12 -o dist

Esto produce los artefactos instalables en dist/ (la versión exacta en el nombre del archivo proviene de version en pyproject.toml, actualmente 0.2.0):

dist/
  mcp_stark_brain-0.2.0-py3-none-any.whl
  mcp_stark_brain-0.2.0.tar.gz

Distribuye el .whl a los desarrolladores (o a una ubicación compartida).

Sin uv: crea un venv con python3.12 -m venv .venv312, actívalo y luego pip install build && python -m build -o dist. Compruébalo primero con python3.12 --version — si ese comando no se encuentra, instala Python 3.12 antes de continuar; no compiles con una versión major/minor diferente.

7. Instalar el MCP en el IDE

Instala la rueda como una herramienta aislada, fijando de nuevo Python 3.12 explícitamente para que el entorno de la herramienta coincida con el que se usó para compilar/probar. Usa un glob para que nunca tengas que editar manualmente un número de versión (y arriesgarte a instalar una rueda obsoleta de una compilación anterior):

# with uv (recommended)
uv tool install --python 3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

# or with pipx
pipx install --python python3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

Esto expone el comando mcp-stark-brain en tu PATH.

Luego añade el servidor a la configuración MCP de tu IDE (por ejemplo, ~/.cursor/mcp.json de Cursor o el .cursor/mcp.json del proyecto):

{
  "mcpServers": {
    "stark-brain": {
      "command": "mcp-stark-brain",
      "env": {
        "ALEXANDRIA_GITHUB_PAT": "<your-personal-fine-grained-PAT>",
        "STARKBANK_PRIVATE_KEY_PATH": "/Users/you/.config/mcp-stark-brain/privateKey.pem",
        "STARKBANK_PROJECT_ID": "<your-project-id>",
        "STARKBANK_DEV_BASE_URL": "https://development.api.starkbank.com",
        "STARKBANK_SANDBOX_BASE_URL": "https://sandbox.api.starkbank.com"
      }
    }
  }
}

Reinicia/recarga el IDE para que detecte el nuevo servidor MCP.

¿Quieres un icono personalizado junto a stark-brain en la lista de Tools & MCP (como el MCP oficial github muestra su logotipo)? Consulta cursor-plugin/README.md para ver un wrapper opcional que empaqueta esta misma configuración como un plugin local de Cursor con un logo. Puramente cosmético: omítelo si no te importa.

8. Actualizar un MCP ya instalado

Cada vez que este repositorio cambie (nuevas herramientas, correcciones de errores, correcciones de configuración predeterminada, etc.), necesitas un nuevo paquete. El comando depende de cómo lo instalaste originalmente — usar el incorrecto es la fuente más común de la confusión de "¿por qué no aparece mi corrección?", así que elige el que coincida con el paso 6:

# 1. Pull the latest source and rebuild the bundle (repo maintainer, or you if you
#    build it yourself). Always clean dist/ first to avoid mixing old/new wheels.
git pull
rm -rf dist
uv build --python 3.12 -o dist

# 2a. If you installed with `uv tool install`, use --reinstall (uv tool upgrade
#     does NOT work for local wheel paths, only for PyPI-published packages):
uv tool install --python 3.12 --reinstall ./dist/mcp_stark_brain-*-py3-none-any.whl

# 2b. If you installed with pipx, uninstall + reinstall (pipx has no local-wheel
#     upgrade command either):
pipx uninstall mcp-stark-brain
pipx install --python python3.12 ./dist/mcp_stark_brain-*-py3-none-any.whl

Luego, consigue que Cursor reinicie el proceso del servidor — la lista de herramientas que ves es lo que ese subproceso stdio anunció al iniciarse, por lo que una reinstalación en disco por sí sola no lo actualiza:

1. Primero, verifica que la reinstalación se aplicó realmente (fuera de Cursor, en una terminal simple):

   uv tool list | grep -A2 mcp-stark-brain   # confirm the version bumped
   which mcp-stark-brain

2. Apaga/enciende el servidor en Cursor — esta es la forma oficialmente soportada de reiniciar un servidor MCP individual sin cerrar toda la aplicación: Cmd+Shift+J -> Tools & MCP -> busca stark-brain -> cámbialo a off, espera unos segundos, cámbialo a on.

3. Abre un chat completamente nuevo. Un chat que ya estaba abierto antes del cambio puede seguir mostrando la lista de herramientas antigua incluso después de que el servidor se reinicie.

4. Si las herramientas aún se ven desactualizadas, significa que el Shared Process de Cursor — un único proceso en segundo plano por instancia de la aplicación que aloja todos los subprocesos MCP (no por ventana, por lo que Developer: Reload Window no lo reinicia) — todavía tiene vivo el subproceso antiguo en memoria. Sal completamente de la aplicación (Cmd+Q, no solo cerrar la ventana) y vuelve a abrirla; eso elimina el Shared Process y todos los subprocesos MCP con él.

5. Para confirmarlo a nivel de protocolo en lugar de adivinar: Cmd+Shift+U -> menú desplegable MCP Logs -> stark-brain -> comprueba que la respuesta de tools/list incluye realmente el nuevo nombre de la herramienta. Si también falta allí, el problema es el paquete instalado, no la caché de Cursor — vuelve al paso 1.

6. Una vez que las nuevas herramientas estén visibles, ejecuta la herramienta status para confirmar que la actualización se aplicó (comprueba que docs_mode, repo, ref, embed_model reflejan lo que esperas).

7. Si solo cambió el contenido de la documentación (no el código), no necesitas reinstalar nada — solo llama a refresh_docs() desde el IDE.

No necesitas regenerar tu PAT ni repetir gcloud auth al actualizar; esas credenciales son independientes de la versión instalada.

9. Primera ejecución y uso

• En la primera llamada a una herramienta de documentación, el servidor obtiene el contenido de alexandria y crea el índice local (esto puede tardar un poco mientras el modelo de embeddings se descarga una vez).

• Usa refresh_docs para volver a sincronizar después de cambios en la documentación (incremental: solo los archivos modificados se vuelven a incrustar).

• status informa del modo de documentación, el número de archivos indexados, el límite de tasa y si las credenciales de la API de Stark Bank están configuradas (starkbank_api_configured).

• Las herramientas de la API de Stark Bank usan development por defecto. Pasa environment="sandbox" solo cuando el usuario pida explícitamente sandbox.

Herramientas disponibles:

10. Modo remoto vs local

• remote (predeterminado): la documentación se obtiene de GitHub a través de tu PAT. Eficiente (tarball = 1 solicitud por actualización), pero consume tu presupuesto de API de GitHub.

• local: la documentación se lee desde un directorio que clonaste tú mismo; cero uso de API.

Cuando el límite de tasa de GitHub está cerca de agotarse, el servidor te advierte y sugiere cambiar. Para cambiar:

# clone the repo once (your own credentials)
git clone git@github.com:starkbank/alexandria.git ~/repos/alexandria

Luego establécelo en mcp.json:

"env": {
  "ALEXANDRIA_GITHUB_PAT": "<pat>",
  "STARK_BRAIN_DOCS_MODE": "local",
  "STARK_BRAIN_DOCS_PATH": "/Users/you/repos/alexandria"
}

o cambia en tiempo de ejecución mediante la herramienta:

set_docs_source(mode="local", path="/Users/you/repos/alexandria")
refresh_docs()

11. Referencia de configuración (variables de entorno)

Consulta .env.example.

12. Solución de problemas

• configuration error: ALEXANDRIA_GITHUB_PAT is required — configura el PAT en tu entorno de mcp.json, o cambia al modo local.

• GitHub 401 — PAT no válido/expirado. Regenera el PAT.

• GitHub 404 («Repo or ref not found») aunque el repositorio exista — para repositorios privados GitHub devuelve 404 tanto cuando un recurso realmente no existe como cuando tu token no puede verlo, por lo que casi siempre es un problema de token/acceso, no un ALEXANDRIA_REPO/ALEXANDRIA_REF incorrecto. La causa más común: un PAT de granularidad fina aún pendiente de aprobación del administrador de la organización (consulta https://github.com/settings/personal-access-tokens — si aparece «Pending», consulta la sección 3 para el paso de aprobación o la alternativa de PAT clásico). Ejecuta diagnose_github_access() para una comprobación en vivo que precise esto.

• GitHub 403 / límite de tasa alcanzado — verifica los permisos del PAT, o clona y usa el modo local.

• GCP credentials not found — ejecuta gcloud auth application-default login.

• Errores de permiso de Datastore/Logging — consultaste un proyecto al que no tienes acceso; elige otro project o solicita acceso.

• Descarga del modelo lenta en la primera ejecución — el modelo de embedding se guarda en caché después del primer uso bajo STARK_BRAIN_CACHE_DIR.

• Una herramienta recién añadida no aparece después de reinstalar — esto es un proceso obsoleto del lado de Cursor, no una instalación defectuosa (consulta la sección 8 paso a paso): el subproceso MCP en ejecución no detecta por sí solo una reinstalación en disco. Apaga/enciende el servidor en Tools & MCP, abre un nuevo chat y, si aún no es suficiente, sal por completo (Cmd+Q) y vuelve a abrir Cursor.

• STARKBANK_PRIVATE_KEY_PATH is not set / fallan las herramientas de API — configura la ruta absoluta a tu PEM y STARKBANK_PROJECT_ID en mcp.json (consulta la sección 5). Confirma que status().starkbank_api_configured es true.

• API de Stark Bank 401 / firma no válida — ID de proyecto incorrecto, PEM no registrado para ese entorno o desfase de reloj. Confirma que la clave pública está registrada en el entorno de Web Banking correspondiente (development vs sandbox).

13. Notas de seguridad

• Tu PAT solo se envía en la cabecera Authorization y nunca se registra.

• La clave privada de Stark Bank se lee del disco en el momento de la solicitud y nunca se registra.

• No se distribuyen claves de cuentas de servicio; el acceso a GCP es tu identidad ADC personal.

• El project de GCP se pasa en cada llamada — no hay proyecto compartido/codificado.

• El cliente rechaza los hosts de producción de la API de Stark Bank.

• .env, *.pem, keys/ y la caché local están ignorados por git.

14. Desarrollo

Los archivos fuente se encuentran directamente bajo src/ (sin anidamiento adicional src/mcp_stark_brain/). La configuración de compilación en pyproject.toml los incluye como el paquete de importación mcp_stark_brain en el wheel (packages = ["src"] + sources = {"src" = "mcp_stark_brain"}), por lo que los puntos de entrada y las importaciones internas permanecen sin cambios independientemente de la estructura en disco.

Ese cambio de nombre no es compatible con instalaciones editables/modo de desarrollo (una limitación de hatchling/pip), por lo que uv sync está configurado con tool.uv.package = false: instala solo dependencias, no el proyecto en sí. conftest.py y scripts/smoke_test.py usan devtools/bootstrap.py para hacer que import mcp_stark_brain funcione directamente contra src/ para pruebas y scripts locales, sin necesidad de paso de instalación.

uv python install 3.12
uv sync --extra dev --python 3.12
uv run ruff check .
uv run pytest
uv run python scripts/smoke_test.py

Para probar realmente el servidor localmente (sin necesidad de compilar wheel):

uv run --python 3.12 python -c "from devtools.bootstrap import ensure_importable; ensure_importable(); from mcp_stark_brain.server import main; main()"