weclapp-api-knowledge-mcp
This MCP server lets you research, explore, and validate the weclapp REST API v2 — both offline via a bundled OpenAPI spec and live against a real tenant.
Knowledge & Exploration (no credentials required)
search_knowledge— Search across entities, fields, endpoints, and relationships by keyword or concept.explain_entity— Get a full breakdown of an entity: fields, endpoints, references, projections, and read notes.explain_endpoint— Look up details about a specific OpenAPI endpoint by path and HTTP method.get_relationships— Discover cross-schema relationships for an entity, including optional inbound references.plan_cross_entity_read— Generate an efficient read plan for fetching data across multiple entities usingpropertiesandincludeReferencedEntities.explain_filter_syntax— Learn weclapp v2 filter syntax, projection options, andincludeReferencedEntitieswith examples.compare_approaches— Compare a naive N+1 approach vs. the recommended efficient read plan for a given goal.
Live Probes (GET-only, requires API credentials)
execute_read_plan— Run a read plan against your live tenant to validate knowledge-layer recommendations.probe_entity_sample— Fetch a bounded sample of a single entity from production for structure inspection.probe_list_query— Run a bounded (capped page size) list query against production.
Analysis & Validation
analyze_response_structure— Analyze a JSON response: discover field paths, arrays, nulls, referenced entities, and types.compare_to_schema— Diff a live API response against the OpenAPI schema fields for an entity.explain_data_location— Find where a specific field lives in a response (top-level, nested, or referenced).validate_read_plan— Verify that a read plan resolved the expected cross-schema data in a response.validate_filter— Check filter shapes and field/operator names against the schema before using them in code or probes.diagnose_api_error— Explain common weclapp API errors and suggest likely fixes.check_field_presence— Confirm whether a field path exists in the OpenAPI spec and optionally in a live response payload.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@weclapp-api-knowledge-mcp Explain the article entity and its relationships."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: OpenAPI Schema Explorer
Tool groups
Knowledge tools:
search_knowledgeexplain_entityexplain_endpointget_relationshipsplan_cross_entity_readexplain_filter_syntaxcompare_approaches
Live probe tools (GET-only and bounded):
execute_read_planprobe_entity_sampleprobe_list_query
Analysis and validation tools:
analyze_response_structurecompare_to_schemavalidate_read_planvalidate_filterdiagnose_api_errorcheck_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-remoteOptional: 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 sync2. 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_KEY3. Run tests (optional)
uv run pytest4. 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 --buildThen 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 |
| For live probes | — | Tenant API base, e.g. |
| For live probes | — | Read-only API token |
| No |
| Auth header name |
| No |
| Path to OpenAPI spec |
| No |
|
|
| No |
| SSE bind host |
| No |
| SSE bind port |
| No |
| Max rows for list probes |
| No |
| HTTP timeout for live probes |
Safety model
No write tools are exposed.
Live probes only issue GET requests.
List probes cap
pageSizewithWECLAPP_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-mcpLicense
MIT — see LICENSE.
Available Tools
17 toolsanalyze_response_structureC
Analyze live or sample JSON: paths, arrays, nulls, referencedEntities, and types.
Inputs: response (required). Returns: object
check_field_presenceC
Check whether a field path exists in OpenAPI and optionally in a live payload.
Inputs: entity (required), field_path (required), response. Returns: object
compare_approachesC
Compare naive N+1 API research with the recommended efficient read plan.
Inputs: root_entity (required), goal (required), needs. Returns: object
compare_to_schemaC
Compare a live payload with the OpenAPI schema fields for an entity.
Inputs: entity (required), response (required). Returns: object
diagnose_api_errorC
Explain common weclapp API errors and likely fixes.
Inputs: error (required). Returns: object
execute_read_planC
Execute a GET-only read plan against production to validate a knowledge-layer recommendation.
Inputs: plan (required). Returns: object
explain_data_locationC
Find where a field appears in a response and whether it is nested or referenced.
Inputs: response (required), field_name (required). Returns: object
explain_endpointB
Explain one OpenAPI endpoint by path and method.
Inputs: path (required), method. Returns: object
explain_entityA
Explain one weclapp entity: fields, endpoints, references, projections, and read notes.
Inputs: entity (required). Returns: object
explain_filter_syntaxC
Explain weclapp v2 filters, projection, includeReferencedEntities, and examples.
Inputs: entity. Returns: object
get_relationshipsC
Return cross-schema relationships discovered from x-weclapp.entity references.
Inputs: entity (required), include_inbound. Returns: object
plan_cross_entity_readC
Plan an efficient read using properties and includeReferencedEntities where possible.
Inputs: root_entity (required), goal (required), root_id, needs. Returns: object
probe_entity_sampleC
Fetch one bounded sample from production for structure research and validation.
Inputs: entity (required), entity_id, filters, properties, +1 more. Returns: object
probe_list_queryB
Probe a bounded list query against production. GET-only, capped page size.
Inputs: entity (required), filters, properties, page_size. Returns: object
search_knowledgeC
Search weclapp API knowledge across entities, fields, endpoints, and relationships.
Inputs: query (required), limit. Returns: object
validate_filterC
Validate filter shape and field/operator names before probing or coding.
Inputs: entity (required), filters (required). Returns: object
validate_read_planC
Validate that a read plan produced the expected cross-schema resolution.
Inputs: plan (required), response (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Each tool has a clearly distinct purpose, covering analysis, validation, querying, and explanation. There is minimal overlap, e.g., execute_read_plan vs validate_read_plan are differentiated by execution vs validation.
All tool names follow a verb_noun pattern in snake_case (e.g., analyze_response_structure, validate_filter). The naming is consistent and predictable across the entire set.
With 17 tools, the server covers a comprehensive range of API knowledge tasks without being excessive. Each tool serves a specific need in exploring and validating the weclapp API.
The tool surface covers major operations: analysis, schema validation, query planning, relationship discovery, and error diagnosis. It lacks some bulk or batch operations, but core workflows are well-supported.
Related MCP Connectors
Read-only MCP server over the developer docs for the portfolio's JSON API, MCP, A2A and NLWeb.
MCP server for MOCO business software: time tracking, projects, budgets, and invoicing via API
MCP server for innovationlab documentation, generated by doc2mcp.
MCP server for the Seline Analytics API
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA MCP server that exposes OpenAPI schema information to LLMs like Claude. This server allows an LLM to explore and understand large OpenAPI schemas through a set of specialized tools, without needing to load the whole schema into the context50MIT
- AlicenseNot gradedqualityBmaintenanceMCP server providing token-efficient access to OpenAPI/Swagger specs via MCP Resources for client-side exploration.582 npm76MIT
- FlicenseNot gradedqualityDmaintenanceA server implementation of the Model Context Protocol (MCP) that provides REST API endpoints for managing and interacting with MCP resources.-
- AlicenseAqualityDmaintenanceMCP server that provides tools for exploring and testing APIs through Swagger/OpenAPI documentation.5230 npm12MIT