Skip to main content
Glama
weclapp-api-knowledge-mcp

weclapp-api-knowledge-mcp

by serenmind

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_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.

Available Tools

17 tools
analyze_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

    B3.2/5.0

    Scored across 17 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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 context
      50
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server providing token-efficient access to OpenAPI/Swagger specs via MCP Resources for client-side exploration.
      582 npm
      76
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A server implementation of the Model Context Protocol (MCP) that provides REST API endpoints for managing and interacting with MCP resources.
      -