Unbundle OpenAPI MCP Server

Unbundle OpenAPI MCP Server

Este projeto fornece um servidor Model Context Protocol (MCP) com ferramentas para dividir arquivos de especificação OpenAPI em vários arquivos ou extrair endpoints específicos para um novo arquivo. Ele permite que um cliente MCP (como um assistente de IA) manipule especificações OpenAPI programaticamente.

Pré-requisitos

• Node.js (versão LTS recomendada, ex.: v18 ou v20)
• npm (vem com Node.js)

Uso

Instalação via Smithery

Para instalar o Unbundle OpenAPI MCP Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @auto-browse/unbundle_openapi_mcp --client claude

A maneira mais fácil de usar este servidor é via npx, o que garante que você esteja sempre usando a versão mais recente sem precisar de uma instalação global.

npx @auto-browse/unbundle-openapi-mcp@latest

Alternativamente, você pode instalá-lo globalmente (geralmente não recomendado):

npm install -g @auto-browse/unbundle-openapi-mcp
# Then run using: unbundle-openapi-mcp

O servidor iniciará e aguardará solicitações MCP na entrada/saída padrão (stdio).

Configuração do Cliente

Para usar este servidor com clientes MCP como VS Code, Cline, Cursor ou Claude Desktop, adicione sua configuração ao respectivo arquivo de configurações. A abordagem recomendada usa npx.

VS Code / Cline / Cursor

Adicione o seguinte ao seu settings.json de Usuário (acessível via Ctrl+Shift+P > Preferences: Open User Settings (JSON)) ou a um arquivo .vscode/mcp.json na raiz do seu workspace.

// In settings.json:
"mcp.servers": {
  "unbundle_openapi": { // You can choose any key name
    "command": "npx",
    "args": [
      "@auto-browse/unbundle-openapi-mcp@latest"
    ]
  }
  // ... other servers can be added here
},

// Or in .vscode/mcp.json (omit the top-level "mcp.servers"):
{
  "unbundle_openapi": { // You can choose any key name
    "command": "npx",
    "args": [
      "@auto-browse/unbundle-openapi-mcp@latest"
    ]
  }
  // ... other servers can be added here
}

Claude Desktop

Adicione o seguinte ao seu arquivo claude_desktop_config.json.

{
	"mcpServers": {
		"unbundle_openapi": {
			// You can choose any key name
			"command": "npx",
			"args": ["@auto-browse/unbundle-openapi-mcp@latest"]
		}
		// ... other servers can be added here
	}
}

Após adicionar a configuração, reinicie o aplicativo cliente para que as alterações tenham efeito.

Ferramentas MCP Fornecidas

split_openapi

Descrição: Executa o comando redocly split para desagrupar um arquivo de definição OpenAPI em vários arquivos menores com base em sua estrutura.

Argumentos:

• apiPath (string, obrigatório): O caminho absoluto para o arquivo de definição OpenAPI de entrada (ex.: openapi.yaml).
• outputDir (string, obrigatório): O caminho absoluto para o diretório onde os arquivos de saída divididos devem ser salvos. Este diretório será criado se não existir.

Retornos:

• Em caso de sucesso: Uma mensagem de texto contendo a saída padrão do comando redocly split (geralmente uma mensagem de confirmação).
• Em caso de falha: Uma mensagem de erro contendo o erro padrão ou detalhes da exceção da execução do comando, marcada com isError: true.

Exemplo de Uso (Solicitação MCP Conceitual):

{
	"tool_name": "split_openapi",
	"arguments": {
		"apiPath": "/path/to/your/openapi.yaml",
		"outputDir": "/path/to/output/directory"
	}
}

extract_openapi_endpoints

Descrição: Extrai endpoints específicos de um arquivo de definição OpenAPI grande e cria um novo arquivo OpenAPI menor contendo apenas esses endpoints e seus componentes referenciados. Isso é alcançado dividindo o arquivo original, modificando a estrutura para manter apenas os caminhos especificados e, em seguida, agrupando o resultado.

Argumentos:

• inputApiPath (string, obrigatório): O caminho absoluto para o arquivo de definição OpenAPI de entrada grande.
• endpointsToKeep (array de strings, obrigatório): Uma lista dos caminhos de endpoint exatos (strings) a serem incluídos na saída final (ex.: ["/api", "/api/projects/{id}{.format}"]). Caminhos não encontrados na especificação original serão ignorados.
• outputApiPath (string, obrigatório): O caminho absoluto onde o arquivo OpenAPI agrupado final e menor deve ser salvo. O diretório será criado se não existir.

Retornos:

• Em caso de sucesso: Uma mensagem de texto indicando o caminho do arquivo criado e a saída padrão do comando redocly bundle.
• Em caso de falha: Uma mensagem de erro contendo detalhes sobre a etapa que falhou (dividir, modificar, agrupar), marcada com isError: true.

Exemplo de Uso (Solicitação MCP Conceitual):

{
	"tool_name": "extract_openapi_endpoints",
	"arguments": {
		"inputApiPath": "/path/to/large-openapi.yaml",
		"endpointsToKeep": ["/users", "/users/{userId}/profile"],
		"outputApiPath": "/path/to/extracted-openapi.yaml"
	}
}

Nota: Este servidor usa npx @redocly/cli@latest internamente para executar os comandos subjacentes split e bundle. Uma conexão com a internet pode ser necessária para npx buscar @redocly/cli se não estiver em cache. Arquivos temporários são criados durante o processo extract_openapi_endpoints e limpos automaticamente.

Desenvolvimento

Se você quiser contribuir ou executar o servidor a partir do código-fonte:

1. Clonar: Clone este repositório.
2. Navegar: cd unbundle_openapi_mcp
3. Instalar Dependências: npm install
4. Compilar: npm run build (compila TypeScript para dist/)
5. Executar: npm start (inicia o servidor usando o código compilado em dist/)