# apidog-mcp

`apidog-mcp` is a stdio MCP server for Apidog. It lets an MCP client such as opencode list projects, inspect API trees, create modules and folders, and add or update requests without configuring every Apidog project by hand.

## Quick start

Use the published package with `npx` from your MCP client configuration.

```json
{
  "mcp": {
    "apidog": {
      "type": "local",
      "command": ["npx", "-y", "@byixlam/apidog-mcp"],
      "environment": {
        "APIDOG_ACCESS_TOKEN": "adgp_xxx",
        "APIDOG_TEAM_ID": "679680"
      }
    }
  }
}
```

`APIDOG_ACCESS_TOKEN` is required for Apidog API calls. The server still starts without it, but tools will return a clear setup error until the token is configured and the MCP client is restarted.

Optional environment variables:

- `APIDOG_TEAM_ID`: default team for `apidog_list_team_projects`.
- `APIDOG_LOCALE`: defaults to `en-US`.
- `APIDOG_CLIENT_VERSION`: defaults to `2.8.34`.

### Configure a default project

Most tools accept `projectId`. If you do not want to pass it every time, run `apidog_configure_project` once in the workspace:

```json
{
  "projectId": 1312991,
  "branchId": 0
}
```

This writes `apidog.json` and adds it to `.gitignore`.

## Tools

### Setup and discovery

- `apidog_check_auth`
- `apidog_configure_project`
- `apidog_list_user_projects`
- `apidog_list_user_teams`
- `apidog_list_team_projects`

### Project navigation

- `apidog_list_modules`
- `apidog_list_environments`
- `apidog_list_api_tree`
- `apidog_list_api_detail_folders`
- `apidog_list_api_responses`
- `apidog_list_test_case_categories`
- `apidog_list_test_case_tags`
- `apidog_list_runners`
- `apidog_get_http_api`

### Modules

- `apidog_create_module`
- `apidog_update_module`
- `apidog_rename_module`
- `apidog_delete_module`

Delete tools require `confirmDelete: true`.

### Folders

- `apidog_create_api_detail_folder`
- `apidog_rename_api_detail_folder`
- `apidog_delete_api_detail_folder`

Delete tools require `confirmDelete: true`.

### Apidog-native requests

These tools work directly with Apidog HTTP API details.

- `apidog_add_request`
- `apidog_update_request`
- `apidog_delete_request`
- `apidog_create_api_detail`
- `apidog_update_api_detail`
- `apidog_delete_api_detail`

Use `apidog_add_request` and `apidog_update_request` for normal request creation and editing. Use the raw `api_detail` tools when you need full control over Apidog-specific fields.

When a URL contains path parameters such as `/users/{id}/posts/{postId}`, the request tools automatically create path parameters for `id` and `postId` unless they already exist.

### OpenAPI import/export

- `apidog_export_openapi`
- `apidog_get_openapi`
- `apidog_validate_openapi`
- `apidog_import_openapi`
- `apidog_add_endpoint`
- `apidog_update_endpoint`
- `apidog_upsert_endpoint`
- `apidog_delete_endpoint`
- `apidog_patch_openapi`

The endpoint tools use an export-modify-validate-import flow. Before importing anything, the server validates the OpenAPI document. `apidog_delete_endpoint` requires both `confirmDelete: true` and `deleteUnmatchedResources: true`.

## Common examples

### Create a folder

```json
{
  "moduleId": 1312066,
  "name": "Billing",
  "parentId": 0,
  "type": "http"
}
```

### Add a request inside a folder

```json
{
  "moduleId": 1312066,
  "folderId": 9034034,
  "name": "Get invoice",
  "method": "get",
  "path": "/invoices/{invoiceId}",
  "status": "developing",
  "responses": [
    {
      "code": 200,
      "name": "Success",
      "contentType": "json",
      "jsonSchema": {
        "type": "object",
        "properties": {
          "invoiceId": { "type": "string" }
        }
      },
      "itemSchema": {}
    }
  ]
}
```

### Add a folder placeholder request

Apidog allows a request with an empty path inside a folder. This is useful for drafts.

```json
{
  "moduleId": 1312066,
  "folderId": 9034034,
  "name": "Draft request",
  "method": "get",
  "path": ""
}
```

### Update an endpoint through OpenAPI

```json
{
  "moduleId": 1312066,
  "path": "/invoices/{invoiceId}",
  "method": "get",
  "patch": {
    "summary": "Get invoice by ID",
    "responses": {
      "200": {
        "description": "Invoice returned"
      }
    }
  }
}
```

### Delete a request

```json
{
  "apiDetailId": 37814603,
  "confirmDelete": true
}
```

## How it works

The server talks to `https://api.apidog.com` and sends the access token as a Bearer token. Project-scoped calls include the project ID and branch ID headers when available.

There are two editing paths:

1. **Direct Apidog tools** for modules, folders, and Apidog-native request details.
2. **OpenAPI tools** for contract-style endpoint changes using Apidog import/export.

Use direct request tools when you care about Apidog-specific fields. Use OpenAPI tools when you want to make portable API contract changes.

## Local development

Install dependencies and build:

```sh
npm install
npm run build
```

Run checks:

```sh
npm run typecheck
npm pack --dry-run
```

Start locally:

```sh
APIDOG_ACCESS_TOKEN=adgp_xxx node dist/index.js
```

The server uses stdio, so it does not print a startup banner.

## Testing safely

When testing write tools against a real Apidog project:

1. Use a disposable project or copy.
2. Create a temporary module with a unique name.
3. Create folders and requests only inside that module.
4. Delete the temporary module when finished.
5. List modules and the API tree to confirm cleanup.

Avoid testing delete tools against existing project resources.

## Notes

This project uses both documented Apidog import/export APIs and endpoints used by the Apidog web app. Those web-app endpoints can change without notice.

Keep destructive tools behind `confirmDelete: true`, and do not store session cookies or other browser session values in this repository.

## Donations

USDT BEP20: `0x589aC54204D9BfBe7E455E09b5fcbD4231C0F55b`