weclapp API Knowledge MCP

A standalone Model Context Protocol server for researching the weclapp 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 for parameter details and usage notes.

Requirements

• Python 3.11+
• 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

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:

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

3. Run tests (optional)

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):

{
  "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

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

Then connect via mcp-remote:

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

More client examples: 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

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

License

MIT — see LICENSE.