# 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**
    ```bash
    cd mcp-server
    npm install
    ```

2.  **Build**
    ```bash
    npm run build
    ```

3.  **Run**
    ```bash
    npm start
    ```

## Testing

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

```bash
# 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:

```bash
cd mcp-server
npm publish --access public
```

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

```bash
npx -y fmea-api-mcp-server
```

## Claude CLI (Quick Setup)

### Option 1: Run with npx (Recommended)
NO installation required. Runs the latest version immediately.

```bash
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:

```bash
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)

```json
{
  "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:

```json
{
  "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:
```bash
npm run build-index
```

### Force Mode (Environment Variable)
You can force a specific backend using `SEARCH_MODE`:

```bash
# 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.
