README.md•6.51 kB
# 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
```bash
# 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
```bash
# 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
```bash
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
```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
```bash
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
```bash
# 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](deploy/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
```bash
# 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](deploy/DOCKER.md)**.