# weclapp API Knowledge MCP

A standalone [Model Context Protocol](https://modelcontextprotocol.io/) server for researching the [weclapp](https://www.weclapp.com/) REST API v2. Use it from Cursor, Claude Desktop, or any MCP-compatible client to explore entities, endpoints, relationships, and filter syntax — and optionally validate read patterns against your own tenant.

**Not affiliated with weclapp.** This is an independent open-source project maintained by the community.

## What it does

It combines:

- **Offline API knowledge** from `data/openapi_v2.json`: entities, endpoints, fields, cross-schema relationships, filter syntax, and efficient read plans.
- **Bounded live probes** against one weclapp tenant: read-only GET requests that validate plans, inspect real response structure, and diagnose API errors.

This is not a CRUD wrapper. Its main job is to answer: *how should I communicate with the weclapp API, where does data live, and how do I fetch cross-schema data efficiently?*

Knowledge tools work without credentials. Live probe tools require a read-only weclapp API token.

## Tool groups

Knowledge tools:

- `search_knowledge`
- `explain_entity`
- `explain_endpoint`
- `get_relationships`
- `plan_cross_entity_read`
- `explain_filter_syntax`
- `compare_approaches`

Live probe tools (GET-only and bounded):

- `execute_read_plan`
- `probe_entity_sample`
- `probe_list_query`

Analysis and validation tools:

- `analyze_response_structure`
- `compare_to_schema`
- `validate_read_plan`
- `validate_filter`
- `diagnose_api_error`
- `check_field_presence`

See [docs/TOOLS.md](docs/TOOLS.md) for parameter details and usage notes.

## Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- Optional: Docker, for SSE transport via `mcp-remote`
- Optional: weclapp API credentials for live probes

## Quick start

### 1. Clone and install

```bash
git clone https://github.com/serenmind/weclapp-api-knowledgebase-mcp.git
cd weclapp-api-knowledgebase-mcp
uv sync
```

### 2. Configure credentials (optional)

Live probe tools need a read-only weclapp token:

```bash
cp .env.example .env
# Edit .env and set WECLAPP_BASE_URL and WECLAPP_API_KEY
```

### 3. Run tests (optional)

```bash
uv run pytest
```

### 4. Connect your MCP client

**Recommended — stdio with Cursor**

Add to your Cursor MCP settings (`.cursor/mcp.json` or Cursor Settings → MCP):

```json
{
  "mcpServers": {
    "weclapp-api-knowledge": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/weclapp-api-knowledgebase-mcp",
        "run",
        "weclapp-api-knowledge-mcp"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

Add `WECLAPP_BASE_URL` and `WECLAPP_API_KEY` to `env` if you want live probes.

**Alternative — Docker + SSE**

```bash
cp .env.example .env
docker compose up --build
```

Then connect via [mcp-remote](https://www.npmjs.com/package/mcp-remote):

```json
{
  "mcpServers": {
    "weclapp-api-knowledge": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8080/sse",
        "--transport",
        "sse-first"
      ]
    }
  }
}
```

More client examples: [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md).

## Environment variables

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `WECLAPP_BASE_URL` | For live probes | — | Tenant API base, e.g. `https://your-tenant.weclapp.com/webapp/api/v2` |
| `WECLAPP_API_KEY` | For live probes | — | Read-only API token |
| `WECLAPP_AUTH_HEADER` | No | `AuthenticationToken` | Auth header name |
| `WECLAPP_OPENAPI_PATH` | No | `data/openapi_v2.json` | Path to OpenAPI spec |
| `MCP_TRANSPORT` | No | `stdio` | `stdio` or `sse` |
| `MCP_HOST` | No | `0.0.0.0` | SSE bind host |
| `MCP_PORT` | No | `8080` | SSE bind port |
| `WECLAPP_MAX_PAGE_SIZE` | No | `10` | Max rows for list probes |
| `WECLAPP_REQUEST_TIMEOUT_SECONDS` | No | `30` | HTTP timeout for live probes |

## Safety model

- No write tools are exposed.
- Live probes only issue GET requests.
- List probes cap `pageSize` with `WECLAPP_MAX_PAGE_SIZE` (default: 10).
- Credentials are read from environment only.
- The bundled OpenAPI file can be refreshed when weclapp updates v2.

## Refreshing the OpenAPI spec

Replace `data/openapi_v2.json` with an updated weclapp v2 OpenAPI export, then restart the server. The MCP server reads and caches the spec directly at runtime.

## Development

```bash
uv sync
uv run pytest
uv run ruff check src tests
MCP_TRANSPORT=stdio uv run weclapp-api-knowledge-mcp
```

## License

MIT — see [LICENSE](LICENSE).