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

Model Context Protocol server for Oracle Cloud Infrastructure

# MCP Oracle Cloud Infrastructure Server

Un servidor Model Context Protocol (MCP) para Oracle Cloud Infrastructure que permite listar y gestionar recursos tipo instancias.

## Documentación

Este proyecto incluye varios documentos para ayudarte a configurar y utilizar el servidor MCP OCI:

- [README.md](README.md) - Este archivo, con información general
- [INSTRUCTIONS.md](INSTRUCTIONS.md) - Guía paso a paso detallada para instalar y configurar
- [CLAUDE-EXAMPLES.md](CLAUDE-EXAMPLES.md) - Ejemplos de cómo usar el servidor con Claude
- [oci-keys-guide.md](oci-keys-guide.md) - Guía para generar claves API para OCI
- [oci-config.example](oci-config.example) - Ejemplo de archivo de configuración OCI
- [CHANGES.md](CHANGES.md) - Registro de cambios importantes y solución de problemas

## Requisitos previos

- Node.js v16 o superior
- npm v8 o superior
- Oracle Cloud Infrastructure CLI configurado
- Oracle Cloud Infrastructure SDK para Node.js
- Model Context Protocol SDK (@modelcontextprotocol/sdk)

## Instalación

Existen varias formas de instalar este paquete:

### Instalación rápida para Claude Desktop

Utiliza el script de instalación automatizado:

```bash
npm run install-claude
```

Este script instalará el paquete globalmente y configurará Claude Desktop automáticamente.

### Instalación global

Puedes instalar este paquete globalmente:

```bash
npm install -g @jocebal/mcp-server-oci
```

O ejecutarlo directamente con npx:

```bash
npx -y @jocebal/mcp-server-oci
```

## Configuración

Este servidor utiliza el archivo de configuración estándar de Oracle Cloud CLI, que normalmente se encuentra en `~/.oci/config`. Asegúrate de que este archivo esté configurado correctamente antes de usar este servidor.

Ejemplo de un archivo de configuración OCI:

```
[DEFAULT]
user=ocid1.user.oc1..aaaaaaaa...
fingerprint=11:22:33:44:55:66:77:88:99:00:aa:bb:cc:dd:ee:ff
tenancy=ocid1.tenancy.oc1..aaaaaaaa...
region=us-ashburn-1
key_file=~/.oci/oci_api_key.pem
```

## Uso

### Iniciar el servidor

Para iniciar el servidor MCP con la configuración por defecto:

```bash
npx -y @jocebal/mcp-server-oci
```

Para especificar un perfil OCI diferente:

```bash
npx -y @jocebal/mcp-server-oci --profile MY_PROFILE
```

Para especificar un puerto diferente:

```bash
npx -y @jocebal/mcp-server-oci --port 3001
```

### Integración con Claude Desktop

Para usar este servidor con Claude Desktop, añade la siguiente configuración a tu archivo `claude_desktop_config.json`:

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

El archivo de configuración 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`

## Herramientas disponibles

Este servidor MCP proporciona las siguientes herramientas:

1. `list_compartments` - Lista todos los compartimentos disponibles en tu cuenta de Oracle Cloud Infrastructure.
2. `list_instances` - Lista todas las instancias de cómputo en un compartimento específico.
3. `get_instance` - Obtiene información detallada sobre una instancia específica.
4. `start_instance` - Inicia una instancia detenida.
5. `stop_instance` - Detiene una instancia en ejecución.
6. `restart_instance` - Reinicia una instancia en ejecución.

## Desarrollo

### Estructura del proyecto

```
mcp-oci-server/
├── src/
│   ├── cli.ts             # Punto de entrada para la interfaz de línea de comandos
│   ├── oci/
│   │   └── client.ts      # Cliente OCI para interactuar con la API de Oracle Cloud
│   ├── server/
│   │   └── server.ts      # Implementación del servidor MCP
│   └── tools/
│       └── oci-tools.ts   # Definición de herramientas MCP para OCI
├── package.json
├── tsconfig.json
└── README.md
```

### Compilación

Existen varias formas de compilar el proyecto:

#### Compilación y empaquetado automatizado

Utiliza el script de compilación automatizado:

```bash
npm run build-package
```

Este script limpiará, compilará y empaquetará el proyecto, y te preguntará si quieres publicarlo en npm.

#### Compilación manual

```bash
npm install
npm run build
```

### Ejecutar en modo desarrollo

```bash
npm run dev
```

## Solución de problemas

Si encuentras errores durante la instalación o compilación, consulta el archivo [CHANGES.md](CHANGES.md) que contiene información detallada sobre los cambios realizados y cómo resolver problemas comunes.

### Error de autenticación

Si recibes errores de autenticación, verifica que:

1. El archivo `~/.oci/config` existe y contiene las credenciales correctas
2. El archivo de clave privada referenciado en el config existe y tiene los permisos correctos
3. Las credenciales en el archivo de configuración son válidas

### Error de conexión

Si el servidor no puede conectarse a OCI, verifica que:

1. Tu conexión a internet funciona correctamente
2. La región configurada en tu archivo de configuración OCI es correcta
3. No hay firewalls o proxies bloqueando la conexión

## Licencia

MIT