Scalable API Catalog Server for LLM Agents

Deployment Hurdles (TODO)

• The base Docker artifact exceeds 2GB pre-model download, ballooning to 3.76GB when models are included. Urgent need for image size reduction.

Configuration Directives

Customization relies on environment variables. Setting GLOBAL_TOOL_PROMPT is CRITICAL for accurate Claude selection.

• OPENAPI_JSON_DOCS_URL: Specifies the URI for the primary OpenAPI specification JSON (default: https://api.staging.readymojo.com/openapi.json).

• MCP_API_PREFIX: Defines the namespace prefix for generated tools (default is "any_openapi"). bash # Generates tools named 'finance_api_request_schema' and 'finance_make_request' docker run -e MCP_API_PREFIX=finance ...

• GLOBAL_TOOL_PROMPT: An optional string prepended to all tool descriptions. This text is vital for guiding Claude's decision-making process regarding tool invocation. bash # Injects context at the start of every description: "Operational APIs for Acme Financial Insights at abc.com. " docker run -e GLOBAL_TOOL_PROMPT="Operational APIs for Acme Financial Services abc.com . " ...

Executive Summary

Motivation: To create a resilient mechanism for interacting with internal, private APIs defined via OpenAPI specs (often hundreds of KBs). - Standard Claude MCP processing fails spectacularly with these specification sizes. - Conversion attempts to YAML proved ineffective and error-prone. - Grouping APIs by category for segmented documentation retrieval also failed due to size constraints.

The Solution: This server implements an in-memory mechanism for vector-based semantic retrieval of relevant API endpoints based on natural language queries (e.g., "retrieve product listings"). - Retrieval is near-instantaneous (milliseconds) because each endpoint is indexed as an independent, fully contextualized chunk.

The Necessary Addition: A secondary utility within this server handles the actual RESTful request execution, necessitated by observed failures in standalone 'fetch' server implementations.

Technical Pipeline: python User_Input -> [Text Embedding] -> FAISS K-Nearest Neighbors -> Retrieved OpenAPI Documentation Chunks -> MCP Agent (Claude) -> Request Payload Construction -> API Execution -> Result Return

Core Capabilities

• 🧠 Dynamic Sourcing: Ingests OpenAPI JSON directly from a remote URL, eliminating local filesystem dependency and ensuring API changes are reflected without redeployment.
• 🔍 Semantic Indexing: Utilizes an optimized MiniLM-L3 embedding model (43MB footprint).
• 🚀 Performance: Built on an asynchronous FastAPI backbone.
• 🧠 Context Preservation: Chunks specifications at the endpoint level, ensuring complete context (path, parameters, schema) is preserved for large specifications (100KB+).
• ⚡ Rapid Lookup: Employs in-memory FAISS indexing for near-zero latency discovery.

Known Constraints

• 🚫 Incompatible with linux/arm/v7 builds due to Transformer library compilation issues.
• 🐢 Initial model load incurs a noticeable cold start delay (~15s) if not run via the pre-loaded Docker image.
• [Legacy Note] Older images required live model downloads from Hugging Face during startup, creating a dependency risk. The current image embeds models to mitigate this.

Multi-Instance Deployment Example

This configuration allows running separate catalog instances, each pointing to a distinct API set, enabling flexible multi-API agent support:

{ "mcpServers": { "finance_openapi": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "OPENAPI_JSON_DOCS_URL=https://api.finance.com/openapi.json", "-e", "MCP_API_PREFIX=finance", "-e", "GLOBAL_TOOL_PROMPT='Financial insights access for ACME Corp.'", "buryhuang/mcp-server-any-openapi:latest" ] }, "healthcare_openapi": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "OPENAPI_JSON_DOCS_URL=https://api.healthcare.com/openapi.json", "-e", "MCP_API_PREFIX=healthcare", "-e", "GLOBAL_TOOL_PROMPT='Secure APIs for Health Data Services.'", "buryhuang/mcp-server-any-openapi:latest" ] } } }

In this layout: - The server automatically deduces base hostnames (https://api.finance.com, etc.) from the specs. - The base URL for execution can be explicitly mandated via API_REQUEST_BASE_URL:

{ "mcpServers": { "finance_openapi": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "OPENAPI_JSON_DOCS_URL=https://api.finance.com/openapi.json", "-e", "API_REQUEST_BASE_URL=https://api.finance.staging.com", "-e", "MCP_API_PREFIX=finance", "-e", "GLOBAL_TOOL_PROMPT='Financial insights access for ACME Corp.'", "buryhuang/mcp-server-any-openapi:latest" ] } } }

Claude Desktop Interaction Example

Agent Prompt Configuration:

Instruct the agent to use the 'financial_api_request_schema' tool for specification details.

The primary task is execution via the 'financial_make_request' tool. Adherence to security protocols, such as including the Authorization header (Bearer ), is mandatory.

Crucially: The schema response will contain the necessary base URL; manual specification is unnecessary.

Chat Interaction Example:

Query the current stock valuations.

Acquisition Methods

Installation via Smithery

For automated setup in Claude Desktop environments using Smithery:

bash npx -y @smithery/cli install @baryhuang/mcp-server-any-openapi --client claude

Python Package Manager

bash pip install mcp-server-any-openapi

Exposed Tools

The service dynamically generates two tools based on the configured {prefix}:

{prefix}_api_request_schema

Retrieves the structured definition for API endpoints matching the user's intent. Output includes the path, HTTP verb, parameter requirements, and response structure.

Input Schema:

{ "query": { "type": "string", "description": "A descriptive phrase detailing the desired API action (e.g., 'Retrieve list of active users', 'Initiate new order entry')" } }

{prefix}_make_request

The core execution mechanism, ensuring robustness where abstract HTTP functions fail. Supports comprehensive request construction.

Input Schema:

{ "method": { "type": "string", "description": "HTTP verb", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"] }, "url": { "type": "string", "description": "The complete, resolved API endpoint URI." }, "headers": { "type": "object", "description": "Key-value pairs for request headers (optional)" }, "query_params": { "type": "object", "description": "URL query string parameters (optional)" }, "body": { "type": "object", "description": "Payload data required for POST, PUT, or PATCH operations (optional)" } }

Service Response Format:

{ "status_code": 200, "headers": { "content-type": "application/json", ... }, "body": { / Response payload / } }

Containerization Details

Multi-Arch Builds

Official container images support three architectures via buildx: bash

Setup buildx and execute multi-platform build/push

docker buildx create --use docker buildx build --platform linux/amd64,linux/arm64 \ -t buryhuang/mcp-server-any-openapi:latest \ --push .

Naming Flexibility

Tool prefixes are configurable via MCP_API_PREFIX: bash

Results in tools prefixed with "finance_api_..."

docker run -e MCP_API_PREFIX=finance_ ...

Supported Architectures

• amd64 (x86_64)
• arm64

Option 1: Pull Prebuilt Image (Docker Hub)

bash docker pull buryhuang/mcp-server-any-openapi:latest

Option 2: Local Source Build

bash docker build -t mcp-server-any-openapi .

Running The Service

bash docker run \ -e OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json \ -e MCP_API_PREFIX=finance \ buryhuang/mcp-server-any-openapi:latest

Internal Architecture Focus

1. EndpointSearcher: The core logic component responsible for specification ingestion, embedding generation, index construction, query interpretation, and documentation serialization.

2. Server Implementation: A high-concurrency FastAPI layer managing the MCP communication protocol, tool registration, and request routing.

Local Source Execution

bash python -m mcp_server_any_openapi

Claude Desktop Integration Example

Configuration snippet for the Claude Desktop MCP server list:

{ "mcpServers": { "any_openapi": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json", "-e", "MCP_API_PREFIX=finance", "-e", "GLOBAL_TOOL_PROMPT='Financial insights access for ACME Corp.'", "buryhuang/mcp-server-any-openapi:latest" ] } } }

Development Guidelines

1. Clone the repository.
2. Create a feature branch (git checkout -b feat/new-enhancement).
3. Commit changes (git commit -m 'Improve feature XYZ').
4. Push the branch (git push origin feat/new-enhancement).
5. Submit a Pull Request.

Licensing

This project is distributed under the terms specified in the LICENSE file.

Implementation Deep Dive

• Granular Processing: Focuses on individual API routes, avoiding the context dilution and performance degradation associated with processing entire specification documents, especially when dealing with complex parameter sets.
• Optimization: Handles specifications up to approximately 10MB (estimated 5,000 endpoints) through:
  • Deferring the loading of large schema components.
  • Concurrent parsing of path definitions.
  • Intelligent omission of redundant descriptive metadata during embedding creation.

---

Contextual Note on Business Tools: Business management utilities encompass systems, applications, and methodologies designed to help organizations adapt to market shifts, maintain competitive standing, and boost operational efficiency. Categorization can occur by departmental function (e.g., planning, control, record-keeping) or by core business aspect (e.g., process improvement, decision support, data validation). Modern business software, evolving from MIS to ERP and cloud solutions, requires careful selection and adaptation to organizational needs to deliver true value, rather than merely adopting the latest trend.