API Docs MCP Server

This project is a Model Context Protocol (MCP) server that provides API specifications from the endpoints directory to AI assistants (Claude, Zed, etc.).

Installation & Execution (NPM)

This project runs in a Node.js environment.

1. Install Dependencies

   cd mcp-server
   npm install

2. Build

   npm run build

3. Run

   npm start

Testing

Test scripts are located in the tests/ directory. Available tests:

# Run basic MCP verification
npm test

# Test synonym/word normalization
npm run test:synonyms

# Test plural/singular keyword matching
npm run test:plural

# Test search enhancement features
npm run test:search

Publishing

To publish the package to NPM, use the following command:

cd mcp-server
npm publish --access public

After publishing, you can run it from anywhere using npx:

npx -y fmea-api-mcp-server

Claude CLI (Quick Setup)

Option 1: Run with npx (Recommended)

NO installation required. Runs the latest version immediately.

claude mcp add fmea-api --transport stdio -- npx -y fmea-api-mcp-server

Option 2: Install Globally

If you prefer to install the package globally on your system:

npm install -g fmea-api-mcp-server
claude mcp add fmea-api --transport stdio -- fmea-api-mcp-server

Client Configuration (Load Configuration)

To use this server with clients like Claude Desktop or Zed, add the following to your configuration file.

Local Execution (Source-based)

{
  "mcpServers": {
    "api-docs": {
      "command": "node",
      "args": [
        "/absolute/path/to/fmea-api-mcp/mcp-server/dist/index.js"
      ],
      "env": {
        "ENDPOINTS_DIR": "/absolute/path/to/fmea-api-mcp/endpoints"
      }
    }
  }
}

Note: set SEARCH_MODE to "file" to force legacy file search, or omit it for auto-detection.

NPX Execution (Published Package-based)

When the package is published to NPM:

{
  "mcpServers": {
    "api-docs": {
      "command": "npx",
      "args": [
        "-y",
        "fmea-api-mcp-server"
      ],
      "env": {
      }
    }
  }
}

Note: The package includes the pre-built search index, so it defaults to Orama search automatically. You can force legacy mode by setting SEARCH_MODE=file.

• Note: The endpoints directory containing API specifications is included in the package, so no extra configuration is needed.

🔍 Search Configuration

The server supports two search backends:

1. Orama (Hybrid Search): High-performance, in-memory vector search. (Default if index exists)
2. FileSearch (Legacy): Scans files on disk at runtime. (Fallback)

Auto-Detection (Recommended)

By default, the server checks for mcp-server/data/search-index.oxy.

• If present -> Orama Mode
• If absent -> File Mode

To enable Orama, simply run the build script before starting:

npm run build-index

Force Mode (Environment Variable)

You can force a specific backend using SEARCH_MODE:

# Force Orama (Requires index)
SEARCH_MODE=orama npm start

# Force Legacy File Search
SEARCH_MODE=file npm start

Features

• Resources: Can read JSON files in the endpoints folder.
• Tools:
  • search_apis:
    • Smart Search: Supports multi-keyword matching (e.g., "project search"). Results are ranked by relevance (Summary > OperationID > Description > Path).
    • Deprecation Warnings: Automatically detects if a V1 endpoint has a V2 equivalent and includes a warning in the results.
    • Supports filters: query (use * for all), method, version, page (default 1).
    • Results limited to 10 per page. Returns meta info (total, totalPages) and guidance.
  • get_api_details:
    • Get full details (schema, parameters) for a specific endpoint.
    • Includes Deprecation Warnings if a newer version of the API exists.