@jorgeceballos/mcp-server-oci/INSTRUCTIONS.md

Model Context Protocol server for Oracle Cloud Infrastructure

# Guía paso a paso para configurar y usar el Servidor MCP OCI

## 1. Instalación

**Importante**: Este proyecto utiliza `@modelcontextprotocol/sdk` (no `@modelcontextprotocol/mcp-sdk`), que es la implementación oficial del protocolo MCP. Si encuentras errores durante la instalación, consulta el archivo `CHANGES.md` para ver los cambios que se han realizado para solucionar problemas con dependencias. Asegúrate de instalar todas las dependencias antes de ejecutar el servidor.

### Instalación desde el repositorio local

Para instalar y ejecutar el proyecto desde el repositorio local:

```bash
# Navega al directorio del proyecto
cd /Users/jocebal/Work/mcp-oci-server

# Instala las dependencias
npm install

# Compila el código TypeScript
npm run build

# Ejecuta el servidor en modo desarrollo
npm run dev
```

### Instalación como paquete global

Si quieres instalar el paquete globalmente en tu sistema:

```bash
# Primero, navega al directorio del proyecto y crea el paquete
cd /Users/jocebal/Work/mcp-oci-server
npm install
npm run build
npm pack

# Instala el paquete globalmente
npm install -g ./jocebal-mcp-server-oci-1.0.0.tgz

# Ahora puedes ejecutar el servidor desde cualquier ubicación
mcp-server-oci
```

## 2. Configuración de Oracle Cloud Infrastructure

El servidor depende de una configuración válida de OCI CLI. Si aún no has configurado OCI CLI, sigue estos pasos:

### Instalar OCI CLI

```bash
# macOS/Linux
bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"

# Windows (PowerShell)
powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.ps1'))"
```

### Configurar OCI CLI

```bash
oci setup config
```

Este comando te guiará a través del proceso de configuración, solicitándote:

1. Ubicación del archivo de configuración (por defecto: ~/.oci/config)
2. Usuario OCID (desde la consola de OCI)
3. Tenancy OCID (desde la consola de OCI)
4. Región (p.ej., us-ashburn-1)
5. Generará un par de claves RSA para la autenticación

Una vez completada la configuración, verifica que funcione correctamente:

```bash
oci os ns get
```

Esto debería devolver tu namespace de Object Storage, lo que confirma que la configuración es correcta.

## 3. Configuración de Claude Desktop

Para integrar el servidor MCP OCI con Claude Desktop, necesitas configurar el archivo `claude_desktop_config.json`. Este archivo debe estar ubicado en:

- macOS: `/Users/jocebal/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

### Crear/editar el archivo de configuración

```bash
# Crear el directorio si no existe (macOS)
mkdir -p "/Users/jocebal/Library/Application Support/Claude"

# Editar el archivo de configuración
nano "/Users/jocebal/Library/Application Support/Claude/claude_desktop_config.json"
```

### Contenido del archivo de configuración

Añade la siguiente configuración al archivo:

```json
{
  "tools": {
    "oracle-cloud": {
      "command": "/Users/jocebal/.nvm/versions/node/v22.15.0/bin/npx",
      "args": [
        "-y",
        "@jocebal/mcp-server-oci",
        "--profile",
        "DEFAULT"
      ],
      "env": {}
    }
  }
}
```

**Nota importante:** Asegúrate de que la ruta al ejecutable `npx` sea correcta. Si no estás usando nvm, puedes usar la ruta global a npx:

```bash
# Encuentra la ruta a npx
which npx
```

## 4. Publicación del paquete (opcional)

Si quieres publicar el paquete en npm para que otros usuarios puedan instalarlo fácilmente:

```bash
# Navega al directorio del proyecto
cd /Users/jocebal/Work/mcp-oci-server

# Inicia sesión en npm
npm login

# Publica el paquete
npm publish --access public
```

## 5. Uso del servidor MCP OCI

### Iniciar el servidor manualmente

```bash
# Usando el paquete instalado globalmente
mcp-server-oci

# O usando npx
npx -y @jocebal/mcp-server-oci

# Con un perfil específico
npx -y @jocebal/mcp-server-oci --profile MY_PROFILE

# Con un puerto específico
npx -y @jocebal/mcp-server-oci --port 3001
```

### Uso desde Claude Desktop

1. Abre Claude Desktop
2. Asegúrate de que la configuración en `claude_desktop_config.json` es correcta
3. Claude debería reconocer automáticamente la herramienta "oracle-cloud"
4. Puedes pedirle a Claude que interactúe con tu infraestructura OCI, por ejemplo:
   - "Muestra todas mis instancias en Oracle Cloud"
   - "Inicia la instancia [nombre] en Oracle Cloud"
   - "Dame detalles sobre la instancia [id]"

## 6. Ejemplos de uso con Claude

Aquí hay algunos ejemplos de cómo puedes interactuar con la infraestructura OCI a través de Claude:

### Listar compartimentos

```
Claude, por favor lista todos los compartimentos disponibles en mi cuenta de Oracle Cloud.
```

### Listar instancias

```
Claude, muestra todas las instancias en el compartimento [compartment-id].
```

### Iniciar una instancia

```
Claude, inicia la instancia con ID [instance-id] en Oracle Cloud.
```

### Detener una instancia

```
Claude, detén la instancia [instance-id] en Oracle Cloud.
```

### Obtener detalles de una instancia

```
Claude, dame todos los detalles de la instancia [instance-id].
```

## 7. Solución de problemas

### Error de conexión

Si Claude no puede conectarse al servidor MCP:

1. Verifica que el servidor esté en ejecución
2. Comprueba la configuración en `claude_desktop_config.json`
3. Asegúrate de que las rutas en la configuración sean correctas
4. Verifica los logs del servidor para ver si hay errores

### Error de autenticación OCI

Si el servidor no puede autenticarse con OCI:

1. Verifica que el archivo `~/.oci/config` exista y tenga los permisos correctos
2. Comprueba que las credenciales en el archivo sean válidas
3. Asegúrate de que la clave privada referenciada en el config exista y tenga los permisos correctos

### Problemas con las herramientas

Si las herramientas no funcionan correctamente:

1. Verifica que los permisos de IAM en Oracle Cloud sean suficientes para las operaciones que intentas realizar
2. Comprueba que estás usando el ID de compartimento o instancia correcto
3. Asegúrate de que la región configurada en tu archivo de configuración OCI sea correcta

## 8. Desarrollo y personalización

Si quieres personalizar o extender el servidor MCP OCI:

1. Clona el repositorio
2. Añade nuevas herramientas en el archivo `src/tools/oci-tools.ts`
3. Agrega nuevas funcionalidades al cliente OCI en `src/oci/client.ts` 
4. Compila y prueba los cambios con `npm run build` y `npm run dev`

### Ejemplo: Añadir una nueva herramienta

Si quisieras añadir una herramienta para listar balanceadores de carga, podrías:

1. Añadir un nuevo método en el cliente OCI (`src/oci/client.ts`):

```typescript
/**
 * List load balancers in a compartment
 */
async listLoadBalancers(compartmentId: string): Promise<any[]> {
  // Implementar la lógica para listar balanceadores de carga
  // ...
}
```

2. Añadir una nueva herramienta en `src/tools/oci-tools.ts`:

```typescript
/**
 * List load balancers in a compartment
 */
public listLoadBalancers: Tool<ListInstancesParams> = {
  name: 'list_load_balancers',
  description: 'Lists all load balancers in a specific compartment',
  parameters: {
    type: 'object',
    properties: {
      compartmentId: {
        type: 'string',
        description: 'The OCID of the compartment to list load balancers from'
      }
    },
    required: ['compartmentId']
  },
  handler: async ({ compartmentId }) => {
    try {
      const loadBalancers = await this.ociClient.listLoadBalancers(compartmentId);
      return loadBalancers;
    } catch (error) {
      console.error('Error listing load balancers:', error);
      throw new Error(`Failed to list load balancers: ${(error as Error).message}`);
    }
  }
};
```

3. Añadir la nueva herramienta al método `getAllTools()`:

```typescript
public getAllTools(): Tool<any>[] {
  return [
    this.listCompartments,
    this.listInstances,
    this.getInstance,
    this.startInstance,
    this.stopInstance,
    this.restartInstance,
    this.listLoadBalancers  // Añadir aquí
  ];
}
```