belle-mcp-server

Un servidor de referencia del Model Context Protocol (MCP) que expone datos reales de gestión de propiedades de Belle Realty (propiedades, inquilinos, contratos de arrendamiento, partes de mantenimiento, renta) como herramientas que Claude Desktop, Cursor o cualquier cliente compatible con MCP puede invocar directamente.

Seis herramientas. Cinco son estrictamente de solo lectura. Una es una propuesta de escritura controlada por HITL. Esa proporción es intencionada y es el objetivo principal de este repositorio.

Parte del AI Fluency Program — Nivel 2.

Por qué existe esto

La mayoría de las demostraciones de "IA + tus datos" otorgan al modelo acceso sin restricciones a la base de datos. Eso es un riesgo.

El Model Context Protocol está diseñado para exponer una superficie pequeña y seleccionada con autenticación por herramienta, límites de tasa y auditoría: la misma disciplina que aplicarías a una API REST pública. Este repositorio muestra cómo se ve eso para un dominio real (un centro comercial de Luisiana) con un esquema Postgres real, una semilla funcional y una única ruta de escritura controlada por HITL.

Si entiendes este repositorio, puedes crear uno para cualquier negocio que dirijas.

Qué incluye

Cada llamada tiene límite de tasa (60/min por defecto) y se registra en el registro de auditoría mcp_audit_log.

Inicio rápido

# 1. Clone + install
git clone https://github.com/OrangeOnyx/belle-mcp-server.git
cd belle-mcp-server
npm install

# 2. Configure
cp .env.example .env
# Paste your Supabase URL + service-role key

# 3. Set up the schema (Supabase project)
#    Copy supabase/migrations/0001_init.sql into the SQL editor and run.

# 4. Seed demo data
npm run db:seed

# 5. Build + inspect
npm run build
npm run inspect

El MCP Inspector abre una interfaz donde puedes listar herramientas, invocarlas y ver las respuestas en bruto.

Conéctalo a Claude Desktop

Añade lo siguiente a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o el equivalente en Windows/Linux:

{
  "mcpServers": {
    "belle-realty": {
      "command": "node",
      "args": ["/absolute/path/to/belle-mcp-server/dist/index.js"],
      "env": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

Reinicia Claude Desktop. Ahora verás un conjunto de herramientas belle-realty. Prueba con:

"¿Qué locales están ocupados actualmente en On The Boulevard y cuánto alquiler mensual generan?"

Claude llamará a get_rent_roll y responderá con los datos devueltos.

El patrón de escritura HITL

La única herramienta de escritura (draft_maintenance_response) ilustra un patrón general que deberías copiar para cualquier servicio orientado a IA:

1. La IA propone un cambio (aquí, una respuesta a un parte de mantenimiento de un inquilino).

2. El servidor lo guarda como approved=false.

3. Nada se entrega, envía ni aplica hasta que un humano lo aprueba fuera de banda (normalmente en la interfaz de administración del gestor de la propiedad).

4. La superficie MCP deliberadamente no expone una herramienta de aprobación. La aprobación es una operación exclusivamente humana.

Esto significa que un agente demasiado entusiasta o con inyección de prompts no puede enviar texto silenciosamente a un inquilino. Puede proponer, y puede proponer en voz alta. No puede enviar.

Para un tutorial más detallado, consulta docs/hitl-pattern.md.

Guía de uso personal

Eres un propietario particular con 3 casas de alquiler o un pequeño edificio comercial.

1. Ejecuta la migración en tu proyecto Supabase.

2. Siembra con tus propios datos (edita supabase/seed.ts o inserta filas manualmente).

3. Apunta Claude Desktop al servidor.

4. Haz preguntas como "¿qué inquilino tiene un contrato que vence en los próximos 90 días?" o "redacta una respuesta al parte sobre el calentador de agua".

Ya has creado una capa de operaciones de inquilinos nativa de IA que habla tus datos. Te costó una tarde.

Guía de uso empresarial

Diriges Belle Realty (o una empresa de gestión equivalente). Varios empleados necesitan acceso a Claude a los datos de la cartera sin ver SQL en bruto y sin riesgo de escrituras accidentales.

1. Despliega este servidor como un proceso persistente (Railway, Fly o un host Docker).

2. Establece MCP_TRANSPORT=http y MCP_HTTP_TOKEN=<secreto-compartido>.

3. Cada compañero configura Claude Desktop o Cursor con la URL y el token.

4. Las herramientas de solo lectura dan ventaja a todos. La única herramienta de escritura protege la relación con el inquilino.

5. mcp_audit_log te proporciona un registro posterior de cada acción de la IA.

Arquitectura

graph LR
    A[Claude Desktop / Cursor] -->|MCP stdio or HTTP| B[belle-mcp-server]
    B --> C[RateLimiter]
    B --> D[Zod validation]
    B --> E[Supabase Postgres]
    B --> F[mcp_audit_log]
    E --> G[(properties, tenants, leases, tickets)]

Detalles en docs/architecture.md.

Cómo ampliarlo

Añade una nueva herramienta en 4 pasos:

1. Añade un esquema Zod para la entrada en src/schemas/domain.ts (si la forma de los datos es nueva).

2. Crea src/tools/<nombre>.ts con un esquema de input, un manejador y una definición JSON-Schema.

3. Regístralo en src/tools/index.ts.

4. Añade pruebas en tests/.

Toda herramienta de escritura debe seguir el patrón de propuesta de escritura en draft_maintenance_response.

Despliegue

Railway (recomendado para transporte HTTP)

railway up

railway.json compila el servidor y ejecuta node dist/index.js. Establece las variables de entorno en el panel de Railway.

Local (solo stdio)

Solo compila y apunta tu cliente MCP a dist/index.js. No se necesita alojamiento.

Desarrollo

npm run dev       # tsx watch mode
npm run test      # vitest
npm run build     # tsc → dist/
npm run inspect   # MCP Inspector UI

Repositorios relacionados

• lease-abstractor — extrae una abstracción estructurada de un PDF/DOCX de contrato

• support-triage-agent — el mismo patrón HITL aplicado a mensajes de soporte

• diligence-agent — diligencia basada en RAG sobre una carpeta de documentos

• ai-fluency-program — plan de estudios principal

Licencia

MIT — consulta LICENSE.

No es asesoramiento legal, fiscal ni de gestión de propiedades. No lo utilices para decisiones críticas de cumplimiento sin un profesional autorizado.