### Run Project

Source: https://github.com/trongnamvn90/mcp/blob/main/servers/example-server/README.md

Starts the project's main process using npm.

```bash
npm start
```

--------------------------------

### Install npm Packages

Source: https://github.com/trongnamvn90/mcp/blob/main/servers/example-server/README.md

Installs the necessary dependencies for the project using npm.

```bash
npm install
```

--------------------------------

### Example MCP Server Implementation (TypeScript)

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Demonstrates a basic MCP server setup using the Model Context Protocol SDK. It showcases how to register tools, such as an 'echo' tool and a 'calculate' tool with error handling for division by zero, and how to connect the server to a transport layer (e.g., stdio).

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "example-server",
  version: "0.1.0"
});

// Register echo tool
server.tool(
  "echo",
  "Echoes back the input message",
  {
    message: z.string().describe("The message to echo back")
  },
  async ({ message }) => {
    return {
      content: [{ type: "text", text: `Echo: ${message}` }]
    };
  }
);

// Register calculator tool with error handling
server.tool(
  "calculate",
  "Performs basic arithmetic operations",
  {
    operation: z.enum(["add", "subtract", "multiply", "divide"]),
    a: z.number(),
    b: z.number()
  },
  async ({ operation, a, b }) => {
    if (operation === "divide" && b === 0) {
      return {
        content: [{ type: "text", text: "Error: Division by zero" }],
        isError: true
      };
    }
    const result = operation === "add" ? a + b :
                   operation === "subtract" ? a - b :
                   operation === "multiply" ? a * b : a / b;
    return {
      content: [{ type: "text", text: `${a} ${operation} ${b} = ${result}` }]
    };
  }
);

// Start server
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  process.on("SIGINT", async () => {
    await server.close();
    process.exit(0);
  });
}

main().catch(console.error);
```

--------------------------------

### API Doc Management and Credential Workflow Example (Shell)

Source: https://github.com/trongnamvn90/mcp/blob/main/CLAUDE.md

Demonstrates a typical workflow for using the api-scout tool, including adding an API documentation, searching for endpoints, retrieving endpoint details, adding credentials, and making an authenticated API call.

```shell
# Basic flow with API key
1. Add API doc: add_api_doc(id="petstore", name="Petstore API", specUrl="https://petstore3.swagger.io/api/v3/openapi.json")
2. Search endpoints: search_endpoints(query="pet")
3. Get endpoint info: get_endpoint_info(apiDocId="petstore", path="/pet/{petId}", method="GET")
4. Add credential: add_credential(id="petstore-key", name="Petstore API Key", type="apiKey", apiKey="xxx")
5. Call API: call_api(apiDocId="petstore", path="/pet/{petId}", method="GET", pathParams={"petId": "1"}, credentialId="petstore-key")
```

--------------------------------

### api-scout Development Commands (Bash)

Source: https://github.com/trongnamvn90/mcp/blob/main/CLAUDE.md

Provides bash commands for navigating to the api-scout directory, installing dependencies using npm, building the project, running in development watch mode, and starting the server.

```bash
cd api-scout

# Install dependencies
npm install

# Build
npm run build

# Development (watch mode)
npm run dev

# Run server
npm start
```

--------------------------------

### Echo Tool Example

Source: https://github.com/trongnamvn90/mcp/blob/main/servers/example-server/README.md

Demonstrates the 'echo' tool which returns the input message. It requires a 'message' string as an argument.

```json
{
  "name": "echo",
  "arguments": {
    "message": "Hello, World!"
  }
}
```

--------------------------------

### Get Timestamp Tool Example

Source: https://github.com/trongnamvn90/mcp/blob/main/servers/example-server/README.md

Illustrates the 'get_timestamp' tool for retrieving the current time in different formats. An optional 'format' parameter ('iso', 'unix', 'human') can be specified, defaulting to 'iso'.

```json
{
  "name": "get_timestamp",
  "arguments": {
    "format": "human"
  }
}
```

--------------------------------

### Claude Desktop MCP Server Configuration

Source: https://github.com/trongnamvn90/mcp/blob/main/servers/example-server/README.md

Configuration snippet for adding the example MCP server to Claude Desktop. It specifies the command to run and its arguments, including the JavaScript file to execute.

```json
{
  "mcpServers": {
    "example-server": {
      "command": "node",
      "args": ["/absolute/path/to/servers/example-server/dist/index.js"]
    }
  }
}
```

--------------------------------

### Install API Scout using NPM

Source: https://github.com/trongnamvn90/mcp/blob/main/api-scout/README.md

This command installs and runs the API Scout package directly using npx, which is the recommended way for installation and immediate use.

```bash
npx -y @trongnamvn90/api-scout
```

--------------------------------

### Build Project

Source: https://github.com/trongnamvn90/mcp/blob/main/servers/example-server/README.md

Builds the project using npm, typically for production deployment.

```bash
npm run build
```

--------------------------------

### Setup API Key Credential - MCP

Source: https://github.com/trongnamvn90/mcp/blob/main/api-scout/docs/EXAMPLES.md

This snippet illustrates how to add an API key credential for an API, such as the 'Petstore' API for production. It requires a unique ID, name, type, API documentation ID, the actual API key, and the header name for the key.

```json
// Tool: add_credential
{
  "id": "petstore_prod",
  "name": "Production Key",
  "type": "apiKey",
  "apiDocId": "petstore",
  "apiKey": "special-key-123",
  "apiKeyHeader": "api_key"
}
```

--------------------------------

### Discover User Login Endpoints - MCP

Source: https://github.com/trongnamvn90/mcp/blob/main/api-scout/docs/EXAMPLES.md

This example shows how to discover API endpoints related to a specific query, in this case, 'User Login' for the 'petstore' API. The tool takes a query string and an API documentation ID as input.

```json
// Tool: search_endpoints
{
  "query": "login",
  "apiDocId": "petstore"
}
```

--------------------------------

### Calculate Tool Example

Source: https://github.com/trongnamvn90/mcp/blob/main/servers/example-server/README.md

Shows the 'calculate' tool for performing arithmetic operations. It takes an 'operation' string ('add', 'subtract', 'multiply', 'divide') and two numerical operands 'a' and 'b'.

```json
{
  "name": "calculate",
  "arguments": {
    "operation": "add",
    "a": 5,
    "b": 3
  }
}
```

--------------------------------

### Get Timestamp Tool

Source: https://github.com/trongnamvn90/mcp/blob/main/servers/example-server/README.md

The get_timestamp tool returns the current timestamp in various formats like ISO, Unix, or human-readable.

```APIDOC
## POST /tool/get_timestamp

### Description
Returns the current timestamp in various formats.

### Method
POST

### Endpoint
/tool/get_timestamp

### Parameters
#### Request Body
- **format** (string) - Optional - One of "iso", "unix", "human" (default: "iso")

### Request Example
```json
{
  "name": "get_timestamp",
  "arguments": {
    "format": "human"
  }
}
```

### Response
#### Success Response (200)
- **timestamp** (string) - The current timestamp in the requested format

#### Response Example
```json
{
  "timestamp": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Make API Call with Credential - MCP

Source: https://github.com/trongnamvn90/mcp/blob/main/api-scout/docs/EXAMPLES.md

This example demonstrates how to make an API call using a previously set up credential. It specifies the API documentation ID, the endpoint path, HTTP method, any path parameters, and the ID of the credential to use.

```json
// Tool: call_api
{
  "apiDocId": "petstore",
  "path": "/user/{username}",
  "method": "GET",
  "pathParams": {
    "username": "trongnam"
  },
  "credentialId": "petstore_prod"
}
```

--------------------------------

### Install and Build api-scout Server (Bash)

Source: https://github.com/trongnamvn90/mcp/blob/main/README.md

This snippet demonstrates the steps to install dependencies and build the api-scout server. It assumes a Node.js environment and uses npm for package management.

```bash
cd api-scout
npm install
npm run build
```

--------------------------------

### Onboard Petstore API - MCP

Source: https://github.com/trongnamvn90/mcp/blob/main/api-scout/docs/EXAMPLES.md

This snippet demonstrates how to onboard a new API, specifically the 'Petstore' API, into the MCP. It requires the API's specification URL and optionally a hash URL for caching.

```json
// Tool: add_api_doc
{
  "id": "petstore",
  "name": "Petstore API",
  "specUrl": "https://petstore.swagger.io/v2/swagger.json",
  "apiHashUrl": "https://api.petstore.io/meta/hash" // Optional smart cache
}
```

--------------------------------

### Echo Tool

Source: https://github.com/trongnamvn90/mcp/blob/main/servers/example-server/README.md

The echo tool echoes back the provided message. It accepts a single string argument.

```APIDOC
## POST /tool/echo

### Description
Echoes back the input message.

### Method
POST

### Endpoint
/tool/echo

### Parameters
#### Request Body
- **message** (string) - Required - The message to echo back

### Request Example
```json
{
  "name": "echo",
  "arguments": {
    "message": "Hello, World!"
  }
}
```

### Response
#### Success Response (200)
- **echo** (string) - The echoed message

#### Response Example
```json
{
  "echo": "Hello, World!"
}
```
```

--------------------------------

### Usage Example for MCP API Interaction (Shell)

Source: https://github.com/trongnamvn90/mcp/blob/main/README.md

This example illustrates how to interact with an MCP server, specifically for API documentation and calls. It covers adding API docs, searching endpoints, managing credentials, and making authenticated API calls.

```shell
# Add an API documentation (this whitelists the baseURL)
add_api_doc(id="github", name="GitHub API", specUrl="...")

# Search for endpoints
search_endpoints(query="repos")

# Add credentials
add_credential(id="github-token", name="GitHub Token", type="bearer", token="ghp_xxx")

# Call the API
call_api(apiDocId="github", path="/repos/{owner}/{repo}", method="GET",
         pathParams={"owner": "anthropics", "repo": "claude-code"},
         credentialId="github-token")
```

--------------------------------

### Get Detailed API Endpoint Information (TypeScript)

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Retrieves comprehensive details for a specific API endpoint, including parameters, request/response schemas, and example curl commands. Requires an API documentation ID, endpoint path, and HTTP method as input. Returns detailed endpoint specifications.

```typescript
// Get detailed info for pet retrieval endpoint
get_endpoint_info({
  apiDocId: "petstore",
  path: "/pet/{petId}",
  method: "GET",
  resolveSchemas: true
})

// Response
{
  "success": true,
  "endpoint": {
    "method": "GET",
    "path": "/pet/{petId}",
    "summary": "Find pet by ID",
    "description": "Returns a single pet",
    "tags": ["pet"],
    "parameters": [
      {
        "name": "petId",
        "in": "path",
        "required": true,
        "description": "ID of pet to return",
        "schema": {
          "type": "integer",
          "format": "int64"
        }
      }
    ],
    "responses": {
      "200": {
        "description": "successful operation",
        "contentTypes": ["application/json", "application/xml"],
        "schema": {
          "type": "object",
          "properties": {
            "id": { "type": "integer", "format": "int64" },
            "name": { "type": "string", "example": "doggie" },
            "status": {
              "type": "string",
              "enum": ["available", "pending", "sold"]
            }
          }
        }
      },
      "404": {
        "description": "Pet not found"
      }
    },
    "security": [{ "petstore_auth": ["read:pets"] }],
    "curlExample": "curl -X GET \"https://petstore3.swagger.io/api/v3/pet/{petId}\""
  }
}
```

--------------------------------

### Development Watch Mode

Source: https://github.com/trongnamvn90/mcp/blob/main/servers/example-server/README.md

Enables watch mode for development using npm, which often involves automatic rebuilding on file changes.

```bash
npm run dev
```

--------------------------------

### Calculate Tool

Source: https://github.com/trongnamvn90/mcp/blob/main/servers/example-server/README.md

The calculate tool performs basic arithmetic operations like addition, subtraction, multiplication, and division.

```APIDOC
## POST /tool/calculate

### Description
Performs basic arithmetic operations.

### Method
POST

### Endpoint
/tool/calculate

### Parameters
#### Request Body
- **operation** (string) - Required - One of "add", "subtract", "multiply", "divide"
- **a** (number) - Required - First operand
- **b** (number) - Required - Second operand

### Request Example
```json
{
  "name": "calculate",
  "arguments": {
    "operation": "add",
    "a": 5,
    "b": 3
  }
}
```

### Response
#### Success Response (200)
- **result** (number) - The result of the calculation

#### Response Example
```json
{
  "result": 8
}
```
```

--------------------------------

### Adding New MCP Packages (Bash)

Source: https://github.com/trongnamvn90/mcp/blob/main/CLAUDE.md

Steps for creating and setting up a new MCP package within the project structure. This involves creating a directory, initializing npm, copying TypeScript configuration, adding dependencies, and implementing the server logic.

```bash
mkdir -p packages/new-mcp/src
cd packages/new-mcp
npm init -y
# Copy tsconfig.json from api-testing

# Add @modelcontextprotocol/sdk dependency
npm install @modelcontextprotocol/sdk

# Implement tools in src/tools/
# Create server entry point in src/index.ts
```

--------------------------------

### Making Raw API Calls

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Execute API calls to any whitelisted URL without requiring endpoint registration in API documentation. Supports GET, POST, and other methods with optional headers and bodies.

```APIDOC
## Call Raw API

### Description
Executes an API call directly to a specified URL, bypassing the need for registered API documentation, provided the URL is whitelisted.

### Method
`call_raw_api` (conceptual function)

### Parameters
- **url** (string) - Required - The full URL to call.
- **method** (string) - Required - The HTTP method (e.g., `"GET"`, `"POST"`).
- **headers** (object) - Optional - Custom headers to include in the request.
- **body** (object) - Optional - The request body for the API call.
- **credentialId** (string) - Optional - The ID of the credential to use for authentication.

### Request Example 1 (GET Request)
```typescript
call_raw_api({
  url: "https://petstore3.swagger.io/api/v3/store/inventory",
  method: "GET",
  credentialId: "petstore-key"
})
```

### Response Example 1 (Success)
```json
{
  "success": true,
  "response": {
    "status": 200,
    "statusText": "OK",
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      "available": 5,
      "pending": 2,
      "sold": 8
    },
    "duration": 98
  }
}
```

### Request Example 2 (POST Request with Body)
```typescript
call_raw_api({
  url: "https://api.example.com/webhooks/test",
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: {
    event: "test.event",
    data: { key: "value" }
  },
  credentialId: "auto-token-cred"
})
```

### Request Example 3 (Unauthorized URL)
```typescript
call_raw_api({
  url: "https://unauthorized-site.com/api/data",
  method: "GET"
})
```

### Response Example 3 (Error - URL Not Whitelisted)
```json
{
  "success": false,
  "error": "URL is not whitelisted: https://unauthorized-site.com/api/data",
  "suggestion": "Add an API doc with this baseURL to whitelist it. Current whitelisted URLs: https://petstore3.swagger.io/api/v3, https://api.github.com"
}
```
```

--------------------------------

### Generate API Documentation Hash (NestJS)

Source: https://github.com/trongnamvn90/mcp/blob/main/api-scout/README.md

This TypeScript example demonstrates how to generate an MD5 hash of an OpenAPI specification string within a NestJS application. This hash can be exposed via an endpoint to enable API Scout's smart caching functionality.

```typescript
// main.ts
const docString = JSON.stringify(document);
const docHash = crypto.createHash('md5').update(docString).digest('hex');

app.getHttpAdapter().get('/api/docs-hash', (req, res) => {
  res.send(docHash);
});
```

--------------------------------

### Claude Code MCP Configuration (JSON)

Source: https://github.com/trongnamvn90/mcp/blob/main/CLAUDE.md

Illustrates how to configure the api-scout MCP server within a Claude Code MCP configuration file (e.g., ~/.claude/mcp.json or .mcp.json). It specifies the command and arguments to run the api-scout server.

```json
{
  "mcpServers": {
    "api-scout": {
      "command": "node",
      "args": ["/path/to/mcp/api-scout/dist/index.js"]
    }
  }
}
```

--------------------------------

### Add Auto-Token Credentials for Automatic Login and Refresh

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Configure an 'autoToken' credential type for APIs requiring periodic re-authentication. This setup automatically handles login and token refresh based on provided URLs, methods, and response parsing. It supports caching tokens and re-logging in upon encountering specific invalid status codes (e.g., 401, 403). Optionally, a validity check URL can be used before each request.

```typescript
// Add auto-token credential that logs in and refreshes automatically
add_credential({
  id: "auto-token-cred",
  name: "Auto-Refresh Token",
  type: "autoToken",
  loginUrl: "https://api.example.com/auth/login",
  loginMethod: "POST",
  loginBody: {
    username: "service_account",
    password: "service_password_123"
  },
  tokenPath: "data.accessToken",
  tokenHeader: "Authorization",
  tokenPrefix: "Bearer ",
  invalidStatusCodes: [401, 403],
  validityCheckUrl: "https://api.example.com/auth/verify",
  validityCheckMethod: "GET",
  apiDocId: "example-api"
})

// The auto-token credential will:
// 1. Call loginUrl with loginBody on first use
// 2. Extract token from response using tokenPath (e.g., response.data.accessToken)
// 3. Cache token in memory
// 4. Automatically re-login if API returns 401 or 403
// 5. Optionally check validity before each request

// Response
// {
//   "success": true,
//   "credential": {
//     "id": "auto-token-cred",
//     "name": "Auto-Refresh Token",
//     "type": "autoToken",
//     "apiDocId": "example-api",
//     "createdAt": "2025-12-07T11:15:00.000Z"
//   }
// }
```

--------------------------------

### Execution

Source: https://github.com/trongnamvn90/mcp/blob/main/api-scout/docs/TOOLS.md

The `call_api` tool allows you to execute API requests against a known endpoint using specified parameters and credentials.

```APIDOC
## POST /call_api

### Description
Execute an API request against a known endpoint.

### Method
POST

### Endpoint
/call_api

### Parameters
#### Request Body
- **apiDocId** (string) - Required - The ID of the API documentation.
- **path** (string) - Required - The path of the endpoint.
- **method** (string) - Required - The HTTP method of the endpoint.
- **pathParams** (object) - Optional - Path parameters for the request.
- **queryParams** (object) - Optional - Query parameters for the request.
- **body** (object) - Optional - Request body.
- **credentialId** (string) - Optional - The ID of the credential to use for authentication.

### Request Example
```json
{
  "apiDocId": "petstore",
  "path": "/pet",
  "method": "POST",
  "body": {
    "name": "doggie",
    "photoUrls": ["string"]
  },
  "credentialId": "my_api_key_cred"
}
```
```

--------------------------------

### Configure API Scout in Claude Desktop

Source: https://github.com/trongnamvn90/mcp/blob/main/api-scout/README.md

This JSON configuration snippet shows how to integrate API Scout as an MCP server within the Claude Desktop application. It specifies the command and arguments to launch API Scout.

```json
{
  "mcpServers": {
    "api-scout": {
      "command": "npx",
      "args": ["-y", "@trongnamvn90/api-scout"]
    }
  }
}
```

--------------------------------

### Add API Documentation from URL - TypeScript

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Adds API documentation by fetching OpenAPI/Swagger specifications from a remote URL. This action automatically whitelists the API's base URL for subsequent requests. It supports specifying custom base URLs and API hash URLs if needed.

```typescript
add_api_doc({
  id: "petstore",
  name: "Petstore API v3",
  specUrl: "https://petstore3.swagger.io/api/v3/openapi.json"
})

// Response
{
  "success": true,
  "apiDoc": {
    "id": "petstore",
    "name": "Petstore API v3",
    "baseUrl": "https://petstore3.swagger.io/api/v3",
    "version": "1.0.11",
    "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.",
    "endpointCount": 19
  }
}

// Add GitHub API with custom base URL override
add_api_doc({
  id: "github",
  name: "GitHub REST API",
  specUrl: "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
  baseUrl: "https://api.github.com",
  apiHashUrl: "https://api.github.com/meta/version"
})
```

--------------------------------

### Add API Documentation from Content - TypeScript

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Adds API documentation by providing the OpenAPI specification content directly as a string, supporting both JSON and YAML formats. This method is useful for internal or custom APIs where a remote URL is not available. A base URL must be specified.

```typescript
add_api_doc({
  id: "custom-api",
  name: "Custom Internal API",
  specContent: `{
    "openapi": "3.0.0",
    "info": {
      "title": "Custom API",
      "version": "1.0.0"
    },
    "servers": [ { "url": "https://api.example.com" } ],
    "paths": {
      "/users": {
        "get": {
          "summary": "List users",
          "responses": {
            "200": {
              "description": "Success",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "array",
                    "items": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    }
  `,
  baseUrl: "https://api.example.com"
})
```

--------------------------------

### Add Basic Authentication Credentials (TypeScript)

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Stores username and password for HTTP Basic Authentication. Requires a credential ID, name, type ('basic'), username, password, and API documentation ID. Supports updating the password for an existing credential.

```typescript
// Add basic auth credentials
add_credential({
  id: "admin-basic",
  name: "Admin Basic Auth",
  type: "basic",
  username: "admin",
  password: "secure_password_123",
  apiDocId: "internal-api"
})

// Update password for existing credential
update_credential({
  id: "admin-basic",
  password: "new_secure_password_456"
})

// Response
{
  "success": true,
  "credential": {
    "id": "admin-basic",
    "name": "Admin Basic Auth",
    "type": "basic",
    "apiDocId": "internal-api",
    "updatedAt": "2025-12-07T11:00:00.000Z"
  }
}
```

--------------------------------

### Browse API Endpoints and Tags (TypeScript)

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Allows users to list endpoints within a specified API documentation, with options to filter by tag and HTTP method, and to paginate results. It also provides a way to list all tags associated with an API documentation along with their respective endpoint counts.

```typescript
// List all endpoints in an API doc
list_endpoints({
  apiDocId: "petstore",
  limit: 10
})

// Response
{
  "success": true,
  "endpoints": [
    {
      "method": "PUT",
      "path": "/pet",
      "summary": "Update an existing pet",
      "tags": ["pet"]
    },
    {
      "method": "POST",
      "path": "/pet",
      "summary": "Add a new pet to the store",
      "tags": ["pet"]
    }
  ],
  "total": 19
}

// Filter by tag and method with pagination
list_endpoints({
  apiDocId: "petstore",
  tag: "store",
  method: "GET",
  limit: 5,
  offset: 0
})

// List all tags with endpoint counts
list_tags({ apiDocId: "petstore" })

// Response
{
  "success": true,
  "tags": [
    { "name": "pet", "endpointCount": 8 },
    { "name": "store", "endpointCount": 4 },
    { "name": "user", "endpointCount": 7 }
  ]
}
```

--------------------------------

### Manage API Documentation (TypeScript)

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Provides functions to list API documentation with varying levels of detail, retrieve specific API doc information, refresh existing API documentation from its source URL, and remove API documentation entries. It also manages the whitelisting of base URLs for registered APIs.

```typescript
// List all API docs with minimal info
list_api_docs()

// Response
{
  "apiDocs": [
    {
      "id": "petstore",
      "name": "Petstore API v3",
      "baseUrl": "https://petstore3.swagger.io/api/v3"
    },
    {
      "id": "github",
      "name": "GitHub REST API",
      "baseUrl": "https://api.github.com"
    }
  ],
  "whitelistedUrls": [
    "https://petstore3.swagger.io/api/v3",
    "https://api.github.com"
  ]
}

// List with verbose details
list_api_docs({ verbose: true })

// Response
{
  "apiDocs": [
    {
      "id": "petstore",
      "name": "Petstore API v3",
      "baseUrl": "https://petstore3.swagger.io/api/v3",
      "version": "1.0.11",
      "endpointCount": 19,
      "addedAt": "2025-12-07T10:00:00.000Z"
    }
  ],
  "whitelistedUrls": ["https://petstore3.swagger.io/api/v3"]
}

// Get detailed API doc info
get_api_doc({
  id: "petstore",
  includeEndpoints: true,
  includeSchemas: true
})

// Refresh API doc from its original spec URL
refresh_api_doc({ id: "github" })

// Response
{
  "success": true,
  "message": "API doc 'github' refreshed successfully",
  "endpointCount": 245
}

// Remove API doc (unwhitelists the baseURL)
remove_api_doc({ id: "old-api" })

// Response
{
  "success": true,
  "message": "API doc 'old-api' removed successfully. Its baseURL is no longer whitelisted."
}
```

--------------------------------

### Make Raw API Calls to Whitelisted URLs with call_raw_api

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Execute API calls to any URL that has been whitelisted in the system configuration using the `call_raw_api` function. This bypasses the need for endpoint registration in API documentation. It supports various HTTP methods, request bodies, headers, and credential application. Calls to non-whitelisted URLs will result in an error.

```typescript
// Call any whitelisted URL directly
call_raw_api({
  url: "https://petstore3.swagger.io/api/v3/store/inventory",
  method: "GET",
  credentialId: "petstore-key"
})

// Response
// {
//   "success": true,
//   "response": {
//     "status": 200,
//     "statusText": "OK",
//     "headers": {
//       "content-type": "application/json"
//     },
//     "body": {
//       "available": 5,
//       "pending": 2,
//       "sold": 8
//     },
//     "duration": 98
//   }
// }

// POST with body to whitelisted URL
call_raw_api({
  url: "https://api.example.com/webhooks/test",
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: {
    event: "test.event",
    data: { key: "value" }
  },
  credentialId: "auto-token-cred"
})

// If URL is not whitelisted
call_raw_api({
  url: "https://unauthorized-site.com/api/data",
  method: "GET"
})

// Error response
// {
//   "success": false,
//   "error": "URL is not whitelisted: https://unauthorized-site.com/api/data",
//   "suggestion": "Add an API doc with this baseURL to whitelist it. Current whitelisted URLs: https://petstore3.swagger.io/api/v3, https://api.github.com"
// }
```

--------------------------------

### API Documentation Management

Source: https://github.com/trongnamvn90/mcp/blob/main/api-scout/docs/TOOLS.md

Tools for managing API documentation, including importing, removing, listing, and refreshing API specifications. These operations can also manage the whitelisting of API base URLs.

```APIDOC
## POST /add_api_doc

### Description
Import an OpenAPI/Swagger specification. This automatically whitelists the API's `baseUrl` for making calls.

### Method
POST

### Endpoint
/add_api_doc

### Parameters
#### Request Body
- **id** (string) - Required - Unique identifier (e.g., 'petstore')
- **name** (string) - Required - Display name
- **specUrl** (string) - Optional - URL to OpenAPI spec (JSON/YAML)
- **specContent** (string) - Optional - Direct spec content string
- **baseUrl** (string) - Optional - Override auto-detected Base URL
- **apiHashUrl** (string) - Optional - URL returning a hash (MD5) for smart caching

### Request Example
```json
{
  "id": "petstore",
  "name": "Petstore API",
  "specUrl": "http://petstore.swagger.io/v2/swagger.json"
}
```

## DELETE /remove_api_doc

### Description
Remove a registered API doc and revoke its `baseUrl` whitelist.

### Method
DELETE

### Endpoint
/remove_api_doc

### Parameters
#### Request Body
- **id** (string) - Required - ID of the API doc to remove

### Request Example
```json
{
  "id": "petstore"
}
```

## GET /list_api_docs

### Description
List all registered API docs.

### Method
GET

### Endpoint
/list_api_docs

### Parameters
#### Query Parameters
- **verbose** (boolean) - Optional - Include endpoint counts

## POST /refresh_api_doc

### Description
Manually refresh an API doc from its `specUrl`.

### Method
POST

### Endpoint
/refresh_api_doc

### Parameters
#### Request Body
- **id** (string) - Required - ID of the API doc to refresh

### Request Example
```json
{
  "id": "petstore"
}
```
```

--------------------------------

### Add API Key Credentials (TypeScript)

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Stores API key credentials for authentication, supporting default or custom header names. Keys are masked upon retrieval and used internally. Requires a credential ID, name, type ('apiKey'), API documentation ID, and the API key. Optionally accepts an 'apiKeyHeader' for custom header names.

```typescript
// Add API key credential with default header (X-API-Key)
add_credential({
  id: "petstore-key",
  name: "Petstore API Key",
  type: "apiKey",
  apiDocId: "petstore",
  apiKey: "special-key-12345"
})

// Add API key with custom header name
add_credential({
  id: "custom-api-key",
  name: "Custom Service Key",
  type: "apiKey",
  apiKey: "sk_live_abc123xyz789",
  apiKeyHeader: "X-Custom-API-Key",
  apiDocId: "custom-api"
})

// Response
{
  "success": true,
  "credential": {
    "id": "petstore-key",
    "name": "Petstore API Key",
    "type": "apiKey",
    "apiDocId": "petstore",
    "createdAt": "2025-12-07T10:30:00.000Z"
  }
}
```

--------------------------------

### OAuth2 Credentials Management

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Configure OAuth2 authentication with access and refresh tokens.

```APIDOC
## OAuth2 Credentials

Configure OAuth2 authentication with access and refresh tokens.

### `add_credential({ id, name, type, accessToken, refreshToken, clientId, clientSecret, tokenUrl, apiDocId })`

**Description:** Adds a new OAuth2 credential configuration.

**Method:** `POST` (simulated)

**Endpoint:** `/credentials` (simulated)

**Parameters:**
- **id** (string) - Required - A unique identifier for the credential.
- **name** (string) - Required - A human-readable name for the credential.
- **type** (string) - Required - The type of credential, must be 'oauth2'.
- **accessToken** (string) - Required - The OAuth2 access token.
- **refreshToken** (string) - Required - The OAuth2 refresh token.
- **clientId** (string) - Required - The OAuth2 client ID.
- **clientSecret** (string) - Required - The OAuth2 client secret.
- **tokenUrl** (string) - Required - The URL to obtain tokens from.
- **apiDocId** (string) - Optional - The ID of the API documentation this credential is for.

**Request Example:**
```typescript
add_credential({
  id: "oauth-service",
  name: "OAuth2 Service Account",
  type: "oauth2",
  accessToken: "ya29.a0AfH6SMBx...",
  refreshToken: "1//0gZ3xYz...",
  clientId: "123456789.apps.googleusercontent.com",
  clientSecret: "client_secret_abc",
  tokenUrl: "https://oauth2.googleapis.com/token",
  apiDocId: "google-api"
})
```

### `update_credential({ id, accessToken })`

**Description:** Updates an existing OAuth2 credential, typically to refresh the access token.

**Method:** `PUT` (simulated)

**Endpoint:** `/credentials/{id}` (simulated)

**Parameters:**
- **id** (string) - Required - The ID of the credential to update.
- **accessToken** (string) - Required - The new OAuth2 access token.

**Request Example:**
```typescript
update_credential({
  id: "oauth-service",
  accessToken: "ya29.a0AfH6SMCy..."
})
```
```

--------------------------------

### Search API Endpoints - TypeScript

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Searches across all registered API documentation for endpoints matching a given query. Supports filtering by API documentation ID, HTTP method, and tag. Results include details like API doc ID, name, path, method, summary, and relevance score.

```typescript
// Search for pet-related endpoints
search_endpoints({
  query: "pet",
  limit: 5
})

// Response
{
  "results": [
    {
      "apiDocId": "petstore",
      "apiDocName": "Petstore API v3",
      "method": "POST",
      "path": "/pet",
      "summary": "Add a new pet to the store",
      "tags": ["pet"],
      "score": 0.95,
      "matchedFields": ["path", "tags", "summary"]
    },
    {
      "apiDocId": "petstore",
      "apiDocName": "Petstore API v3",
      "method": "GET",
      "path": "/pet/{petId}",
      "summary": "Find pet by ID",
      "tags": ["pet"],
      "score": 0.92,
      "matchedFields": ["path", "tags"]
    }
  ],
  "totalFound": 8
}

// Search with filters
search_endpoints({
  query: "user",
  apiDocId: "github",
  method: "GET",
  tag: "users",
  limit: 10
})
```

--------------------------------

### Credentials Management

Source: https://github.com/trongnamvn90/mcp/blob/main/api-scout/docs/TOOLS.md

Tools for securely storing and managing authentication credentials for various authentication types.

```APIDOC
## POST /add_credential

### Description
Store authentication details securely.

### Method
POST

### Endpoint
/add_credential

### Parameters
#### Request Body
- **id** (string) - Required - Unique identifier for the credential.
- **name** (string) - Required - Display name for the credential.
- **type** (string) - Required - Type of authentication (e.g., "apiKey", "bearer", "basic").
- **apiDocId** (string) - Optional - The ID of the API documentation this credential is for.
- **apiKey** (string) - Optional - API key for apiKey authentication.
- **token** (string) - Optional - Bearer token for bearer authentication.
- **username** (string) - Optional - Username for basic authentication.
- **password** (string) - Optional - Password for basic authentication.
- **loginUrl** (string) - Optional - URL for OAuth2 login.
- **loginBody** (object) - Optional - Request body for OAuth2 login.

### Request Example
```json
{
  "id": "my_api_key_cred",
  "name": "My API Key Credential",
  "type": "apiKey",
  "apiDocId": "petstore",
  "apiKey": "YOUR_API_KEY"
}
```
```

--------------------------------

### API Documentation Management

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Retrieve information about all registered API documentation and manage the whitelist.

```APIDOC
## Listing and Managing API Documentation

Retrieve information about all registered API documentation and manage the whitelist.

### `list_api_docs()`

**Description:** Lists all registered API documentation with minimal information.

**Method:** `POST` (simulated)

**Endpoint:** `/api_docs/list` (simulated)

**Parameters:** None

**Request Example:**
```typescript
list_api_docs()
```

**Response Example (200 OK):**
```json
{
  "apiDocs": [
    {
      "id": "petstore",
      "name": "Petstore API v3",
      "baseUrl": "https://petstore3.swagger.io/api/v3"
    },
    {
      "id": "github",
      "name": "GitHub REST API",
      "baseUrl": "https://api.github.com"
    }
  ],
  "whitelistedUrls": [
    "https://petstore3.swagger.io/api/v3",
    "https://api.github.com"
  ]
}
```

### `list_api_docs({ verbose: true })`

**Description:** Lists all registered API documentation with verbose details.

**Method:** `POST` (simulated)

**Endpoint:** `/api_docs/list?verbose=true` (simulated)

**Parameters:**
- **verbose** (boolean) - Optional - If true, provides detailed information.

**Request Example:**
```typescript
list_api_docs({ verbose: true })
```

**Response Example (200 OK):**
```json
{
  "apiDocs": [
    {
      "id": "petstore",
      "name": "Petstore API v3",
      "baseUrl": "https://petstore3.swagger.io/api/v3",
      "version": "1.0.11",
      "endpointCount": 19,
      "addedAt": "2025-12-07T10:00:00.000Z"
    }
  ],
  "whitelistedUrls": ["https://petstore3.swagger.io/api/v3"]
}
```

### `get_api_doc({ id, includeEndpoints, includeSchemas })`

**Description:** Retrieves detailed information about a specific API documentation.

**Method:** `GET` (simulated)

**Endpoint:** `/api_docs/{id}` (simulated)

**Parameters:**
- **id** (string) - Required - The ID of the API documentation to retrieve.
- **includeEndpoints** (boolean) - Optional - If true, includes endpoint details.
- **includeSchemas** (boolean) - Optional - If true, includes schema details.

**Request Example:**
```typescript
get_api_doc({
  id: "petstore",
  includeEndpoints: true,
  includeSchemas: true
})
```

### `refresh_api_doc({ id })`

**Description:** Refreshes API documentation from its original specification URL.

**Method:** `POST` (simulated)

**Endpoint:** `/api_docs/{id}/refresh` (simulated)

**Parameters:**
- **id** (string) - Required - The ID of the API documentation to refresh.

**Request Example:**
```typescript
refresh_api_doc({ id: "github" })
```

**Response Example (200 OK):**
```json
{
  "success": true,
  "message": "API doc 'github' refreshed successfully",
  "endpointCount": 245
}
```

### `remove_api_doc({ id })`

**Description:** Removes API documentation and unwhitelists its base URL.

**Method:** `DELETE` (simulated)

**Endpoint:** `/api_docs/{id}` (simulated)

**Parameters:**
- **id** (string) - Required - The ID of the API documentation to remove.

**Request Example:**
```typescript
remove_api_doc({ id: "old-api" })
```

**Response Example (200 OK):**
```json
{
  "success": true,
  "message": "API doc 'old-api' removed successfully. Its baseURL is no longer whitelisted."
}
```
```

--------------------------------

### Endpoint Listing and Filtering

Source: https://context7.com/trongnamvn90/mcp/llms.txt

Browse and filter endpoints within API documentation.

```APIDOC
## Listing Endpoints and Tags

Browse and filter endpoints within API documentation.

### `list_endpoints({ apiDocId, limit, tag, method, offset })`

**Description:** Lists endpoints within a specified API documentation, with options for filtering and pagination.

**Method:** `POST` (simulated)

**Endpoint:** `/api_docs/{apiDocId}/endpoints` (simulated)

**Parameters:**
- **apiDocId** (string) - Required - The ID of the API documentation.
- **limit** (integer) - Optional - The maximum number of endpoints to return.
- **tag** (string) - Optional - Filters endpoints by tag.
- **method** (string) - Optional - Filters endpoints by HTTP method (e.g., 'GET', 'POST').
- **offset** (integer) - Optional - The number of endpoints to skip for pagination.

**Request Example (List all endpoints in an API doc):**
```typescript
list_endpoints({
  apiDocId: "petstore",
  limit: 10
})
```

**Response Example (200 OK):**
```json
{
  "success": true,
  "endpoints": [
    {
      "method": "PUT",
      "path": "/pet",
      "summary": "Update an existing pet",
      "tags": ["pet"]
    },
    {
      "method": "POST",
      "path": "/pet",
      "summary": "Add a new pet to the store",
      "tags": ["pet"]
    }
  ],
  "total": 19
}
```

**Request Example (Filter by tag and method with pagination):**
```typescript
list_endpoints({
  apiDocId: "petstore",
  tag: "store",
  method: "GET",
  limit: 5,
  offset: 0
})
```

### `list_tags({ apiDocId })`

**Description:** Lists all tags within an API documentation along with their endpoint counts.

**Method:** `POST` (simulated)

**Endpoint:** `/api_docs/{apiDocId}/tags` (simulated)

**Parameters:**
- **apiDocId** (string) - Required - The ID of the API documentation.

**Request Example:**
```typescript
list_tags({ apiDocId: "petstore" })
```

**Response Example (200 OK):**
```json
{
  "success": true,
  "tags": [
    { "name": "pet", "endpointCount": 8 },
    { "name": "store", "endpointCount": 4 },
    { "name": "user", "endpointCount": 7 }
  ]
}
```
```

--------------------------------

### Discovery & Search

Source: https://github.com/trongnamvn90/mcp/blob/main/api-scout/docs/TOOLS.md

Tools for discovering and searching API endpoints. You can search across all registered API documentation or filter by specific API documentation, method, or tag.

```APIDOC
## POST /search_endpoints

### Description
Search for endpoints across one or all docs.

### Method
POST

### Endpoint
/search_endpoints

### Parameters
#### Request Body
- **query** (string) - Required - Keyword to search in path, summary, etc.
- **apiDocId** (string) - Optional - Limit search to specific doc
- **method** (string) - Optional - Filter by HTTP method (e.g., "GET", "POST")
- **tag** (string) - Optional - Filter by tag
- **limit** (number) - Optional - Maximum number of results to return (default: 20)

### Request Example
```json
{
  "query": "user",
  "apiDocId": "myapi"
}
```

## POST /get_endpoint_info

### Description
Get detailed schema information for a specific endpoint.

### Method
POST

### Endpoint
/get_endpoint_info

### Parameters
#### Request Body
- **apiDocId** (string) - Required - The ID of the API documentation.
- **path** (string) - Required - The path of the endpoint.
- **method** (string) - Required - The HTTP method of the endpoint.
- **resolveSchemas** (boolean) - Optional - Whether to resolve schemas (default: true).

### Request Example
```json
{
  "apiDocId": "petstore",
  "path": "/pet/{petId}",
  "method": "GET"
}
```
```