IRIS ObjectScript MCP Server

Model Context Protocol (MCP) server para documentación de IRIS ObjectScript. Proporciona acceso a documentación, ejemplos y herramientas de búsqueda para el desarrollo con InterSystems IRIS.

🚀 Inicio Rápido

Desarrollo Local

# Instalar dependencias
npm install

# Compilar TypeScript
npm run build

# Ejecutar en modo desarrollo
npm run dev

# Ejecutar con inspector MCP
npm run dev:ins

Deployment con Docker

# Ir al directorio de deployment
cd deploy/

# Setup completo
./docker-manage.sh build
./docker-manage.sh start
./setup-volumes.sh

# Verificar funcionamiento
./docker-manage.sh status

📁 Estructura del Proyecto

iris-mcp/
├── src/                    # Código fuente TypeScript
│   ├── server.ts          # Servidor MCP principal
│   ├── tools/             # Herramientas MCP
│   ├── search/            # Funciones de búsqueda
│   ├── loaders/           # Cargadores de documentación
│   ├── resources/         # Recursos MCP
│   └── request/           # Manejadores de requests
├── data/                  # Datos y cache
│   └── cache/            # Cache de documentación descargada
├── deploy/               # 🐳 Archivos de Docker y deployment
│   ├── Dockerfile
│   ├── docker-compose.yml
│   ├── docker-manage.sh   # Script de gestión principal
│   ├── setup-volumes.sh   # Configuración de volúmenes
│   ├── iris-mcp-wrapper.sh # Wrapper para mcp.json
│   └── DOCKER.md         # Documentación completa de Docker
├── package.json
├── tsconfig.json
└── README.md            # Este archivo

🛠️ Herramientas MCP Disponibles

1. smart_search - Búsqueda inteligente con descarga automática

   • Busca primero en caché local
   • Descarga documentos relevantes si es necesario
   • Mapeo inteligente de términos a KEYs

2. search_objectscript - Búsqueda rápida solo en caché local

   • Búsqueda instantánea en documentos descargados
   • Resultados con contexto y números de línea

3. open_by_key - Abrir documentación por KEY oficial

   • Acceso directo a documentación específica
   • Descarga y cachea automáticamente

4. open_class - Abrir documentación de clase

   • Documatic para clases (ej. %Library.String)
   • Navegación por jerarquía de clases

🐳 Docker Deployment

Para deployment en producción, usa Docker:

Scripts de Gestión (en deploy/)

• docker-manage.sh - Script principal de gestión
• setup-volumes.sh - Configuración de volúmenes bidireccionales
• iris-mcp-wrapper.sh - Wrapper para usar en mcp.json

Comandos Principales

cd deploy/

# Construcción y arranque
./docker-manage.sh build    # Construir imagen
./docker-manage.sh start    # Iniciar contenedor
./setup-volumes.sh          # Configurar permisos

# Gestión diaria
./docker-manage.sh status   # Ver estado
./docker-manage.sh logs     # Ver logs
./docker-manage.sh restart  # Reiniciar

# Mantenimiento
./docker-manage.sh cleanup  # Limpiar todo

📋 Configuración en mcp.json

{
  "mcpServers": {
    "iris-objectscript-docs": {
      "command": "bash",
      "args": ["/ruta/completa/deploy/iris-mcp-wrapper.sh"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Ubicación del archivo:

• macOS: ~/Library/Application Support/Claude/mcp.json
• Windows: %APPDATA%\\Claude\\mcp.json
• Linux: ~/.config/claude/mcp.json

🔧 Desarrollo

Scripts NPM

npm run build     # Compilar TypeScript
npm run start     # Ejecutar servidor compilado
npm run dev       # Desarrollo (compilar + ejecutar)
npm run dev:ins   # Con inspector MCP

Estructura de Código

• server.ts - Punto de entrada del servidor MCP
• tools/ - Definiciones de herramientas MCP
• search/ - Lógica de búsqueda (local y inteligente)
• loaders/ - Descarga y procesamiento de documentación
• resources/ - Recursos y templates MCP

📊 Volúmenes y Persistencia

Configuración Bidireccional

• data/ ↔ Contenedor - Sincronización completa
• logs/ ↔ Contenedor - Logs compartidos

Casos de Uso

• ✅ Modificas archivos localmente → Se reflejan en el contenedor
• ✅ El MCP descarga docs → Aparecen en tu data/cache/
• ✅ Backup/sync de data/ funciona normalmente

🚦 Estados y Flujos

Primera Instalación

1. cd deploy/
2. ./docker-manage.sh build
3. ./docker-manage.sh start
4. ./setup-volumes.sh
5. Configurar mcp.json

Desarrollo Diario

1. ./docker-manage.sh status (verificar)
2. Trabajar normalmente en el código
3. ./docker-manage.sh restart (si cambias código)

Actualización

1. git pull
2. cd deploy/
3. ./docker-manage.sh stop
4. ./docker-manage.sh build
5. ./docker-manage.sh start

🔍 Ejemplo de Uso

# Buscar información sobre clases
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "smart_search", "arguments": {"q": "class methods"}}}' | ./deploy/iris-mcp-wrapper.sh

# Abrir documentación específica
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "open_class", "arguments": {"class": "%Library.String"}}}' | ./deploy/iris-mcp-wrapper.sh

📖 Documentación Adicional

• DOCKER.md - Documentación completa de Docker, scripts y troubleshooting
• Logs: Revisar logs/ o ./docker-manage.sh logs
• Cache: Explorar data/cache/ para ver documentos descargados

🛡️ Seguridad

• Contenedor ejecuta con usuario no-root
• Sin puertos expuestos (MCP usa stdio)
• Volúmenes con permisos mínimos necesarios
• Imágenes basadas en Alpine Linux

🔧 Troubleshooting

# Ver estado del contenedor
cd deploy/ && ./docker-manage.sh status

# Ver logs detallados
cd deploy/ && ./docker-manage.sh logs

# Reset completo
cd deploy/ && ./docker-manage.sh cleanup
cd deploy/ && ./docker-manage.sh build && ./docker-manage.sh start

# Verificar MCP manualmente
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | ./deploy/iris-mcp-wrapper.sh

---

Para documentación detallada de Docker y deployment, consulta deploy/DOCKER.md.