# https://github.com/Data-Everything/MCP-Platform Project Manual Generated at: 2026-06-14 03:28:34 UTC ## Table of Contents - [Platform Overview and System Architecture](#page-overview) - [Built-in Server Templates and Usage Guide](#page-builtin-templates) - [Creating Custom Templates and Extensions](#page-custom-templates) - [Deployment Backends, Configuration Flow, and Client API](#page-deployment-and-client) ## Platform Overview and System Architecture ### Related Pages Related topics: [Built-in Server Templates and Usage Guide](#page-builtin-templates), [Deployment Backends, Configuration Flow, and Client API](#page-deployment-and-client)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/README.md) - [mcp_platform/template/utils/__init__.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/__init__.py) - [mcp_platform/template/utils/creation.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/creation.py) - [mcp_platform/cli/interactive_cli.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/interactive_cli.py) - [mcp_platform/template/templates/demo/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md) - [mcp_platform/template/templates/github/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/github/README.md) - [mcp_platform/template/templates/gitlab/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/gitlab/README.md) - [mcp_platform/template/templates/slack/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/slack/README.md) - [mcp_platform/template/templates/zendesk/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/zendesk/README.md)
# Platform Overview and System Architecture ## Purpose and Scope MCP-Platform is a deployment framework for Model Context Protocol (MCP) servers. It packages a curated set of pre-built server templates (databases, developer tools, ticketing, messaging, search) and provides a unified CLI and runtime that turns a single command into a running, containerized MCP endpoint. The platform's stated goal is to let AI developers focus on integration rather than infrastructure, by replacing ad-hoc Docker, transport, and configuration plumbing with a templated, opinionated workflow. Source: [README.md:9-15]() The project supersedes the legacy `mcp-templates` package. Existing configurations, Docker images, and deployment workflows remain compatible, but the active development line is the `mcp-platform` distribution installed via `pip install mcp-platform` and operated through the `mcpp` command. Source: [README.md:1-7]() ## High-Level System Architecture The platform is organized into three cooperating layers: a **Template Library**, a **Core Engine**, and a **Client/CLI surface**. ```mermaid flowchart TB User([User / LLM Client]) --> CLI[mcpp CLI / Interactive REPL] CLI --> Core[Core Engine\nCacheManager · ConfigProcessor · ResponseFormatter] Core --> Discovery[Template Discovery] Discovery --> Library[(Template Library\ndemo · github · gitlab · slack · zendesk · postgres · bigquery · trino · elasticsearch)] Core --> Deployer[Containerized Deployer] Deployer --> Docker[(Docker Engine)] Docker --> MCPServer[MCP Server Process] MCPServer --> Tools[Tool Surface\nstdio · HTTP · SSE] User -.calls tools.-> Tools ``` The **Template Library** is the canonical set of directories under `mcp_platform/template/templates/`. Each template is a self-contained package (server code, configuration schema, documentation, and Docker assets) that the platform can list, validate, and deploy. Source: [mcp_platform/template/utils/__init__.py:1-8]() The **Core Engine** is a set of utilities for discovering templates, processing configuration, formatting responses, and caching template metadata. The README advertises a 6-hour template cache with automatic invalidation to accelerate repeated operations. Source: [README.md:60-64]() The **Client/CLI surface** is what the operator actually invokes. The non-interactive `mcpp` command handles one-shot lifecycle operations (`list`, `deploy`, `logs`, `tools`, `call`), while the interactive REPL — built on Typer — provides tab completion, command history, and session-style tool execution through `MCPClient`. Source: [mcp_platform/cli/interactive_cli.py:7-19]() ## Template System and Lifecycle A template is more than a script — it is a deployable unit with a structured layout. The reference implementation in `templates/demo/` demonstrates the contract: a `server.py` entry point, a `config.py` schema module, FastMCP-decorated tools, a `requirements.txt`, a Dockerfile, and a docs directory. Source: [mcp_platform/template/templates/demo/README.md:9-14]() Templates are discovered dynamically. The `TemplateDiscovery` utility (exported from `mcp_platform.template.utils`) scans the templates directory and surfaces each entry to the CLI. Source: [mcp_platform/template/utils/__init__.py:7-12]() When an operator needs a new integration that does not exist yet, the `TemplateCreator` class scaffolds one. It is an interactive Rich-based prompt flow that asks for an ID, name, and capabilities, then materializes a complete template directory (config, server stub, tests, docs) by adapting a shared `config.py` template. Source: [mcp_platform/template/utils/creation.py:24-44]() The platform encourages reuse of upstream MCP implementations rather than rewriting them. Several templates wrap existing open-source MCP servers and surface them through a uniform configuration and deployment layer: | Template | Wrapped Capability | Configuration Mechanism | Source | |----------|-------------------|------------------------|--------| | demo | Reference FastMCP server with `say_hello`, `get_server_info`, `echo_message` | `MCP_HELLO_FROM`, `MCP_LOG_LEVEL` env vars | [mcp_platform/template/templates/demo/README.md:53-72]() | | github | 77+ GitHub API tools (repos, issues, PRs, actions) | `GITHUB_PERSONAL_ACCESS_TOKEN` | [mcp_platform/template/templates/github/README.md:1-12]() | | gitlab | 66+ GitLab tools (repos, MRs, pipelines, wiki, milestones) | `GITLAB_PERSONAL_ACCESS_TOKEN`, optional `GITLAB_READ_ONLY_MODE` | [mcp_platform/template/templates/gitlab/README.md:5-28]() | | slack | Channels, DMs, thread reads (XOXP or XOXC/XOXD tokens) | `SLACK_MCP_XOXP_TOKEN` or token pair | [mcp_platform/template/templates/slack/README.md:11-29]() | | zendesk | Tickets, users, knowledge base, analytics | Zendesk API credentials | [mcp_platform/template/templates/zendesk/README.md:1-15]() | Community requests have shaped recent additions. The Postgres template shipped in release 1.3.0, the gateway improvements in the same release, and a Snowflake template has been requested to follow the Postgres pattern (issues #24, #41). The Trino template was rewritten in release 1.2.0 and the Elasticsearch template added dual-engine support. Source: [release notes referenced in community context]() ## Configuration, Transports, and Execution Configuration is intentionally multi-channel. A single deployment can receive values from JSON files, YAML files, environment variables, CLI `--config key=value` flags, or override parameters. The override path performs type conversion (`"true"` → `bool`, `"123"` → `int`, JSON-like strings → `list`/`dict`), which is exercised by the demo template's `demonstrate_overrides` helper. Source: [mcp_platform/template/templates/demo/README.md:21-30]() Transports are abstracted. Templates expose `stdio` (default for many wrapped servers), HTTP (the demo defaults to HTTP on port 7071), and SSE where the upstream server supports it. The interactive CLI routes tool calls through `MCPClient` rather than raw HTTP, ensuring the platform's own error handling and formatting apply uniformly. Source: [mcp_platform/cli/interactive_cli.py:24-31](), [mcp_platform/template/templates/demo/README.md:37-47]() The interactive REPL has been deliberately simplified: the prior implicit "select a template for the session and auto-inject it" behavior has been removed. Commands now require explicit template arguments and surface clear errors when omitted, trading a small ergonomic shortcut for predictable, scriptable behavior. Source: [mcp_platform/cli/interactive_cli.py:42-47]() ## Known Failure Modes and Community Notes - **Documentation drift across templates** is a known issue (#28): the `docs/` directory under each template is inconsistent in its usage instructions. New template authors should follow the demo's structure. - **Stale tool-calling examples** have appeared in some template READMEs (e.g., BigQuery, #27) showing direct API calls rather than the `mcpp` / `MCPClient` flow. The platform's intended path is always through the client or CLI. - **Docs build workflow** has failed on shallow clones due to `setuptools_scm` warnings (#43), which can break the GitHub Actions documentation pipeline if not handled. ## See Also - Template Creation Utility - CLI Reference - Configuration Schema and Overrides - Demo Template Walkthrough - Adding a New Template (Contributor Guide) --- ## Built-in Server Templates and Usage Guide ### Related Pages Related topics: [Creating Custom Templates and Extensions](#page-custom-templates), [Deployment Backends, Configuration Flow, and Client API](#page-deployment-and-client)
Related Source Files The following source files were used to generate this page: - [mcp_platform/template/templates/demo/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md) - [mcp_platform/template/templates/github/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/github/README.md) - [mcp_platform/template/templates/gitlab/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/gitlab/README.md) - [mcp_platform/template/templates/zendesk/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/zendesk/README.md) - [mcp_platform/template/utils/__init__.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/__init__.py) - [mcp_platform/template/utils/creation.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/creation.py) - [mcp_platform/cli/interactive_cli.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/interactive_cli.py) - [README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/README.md)
# Built-in Server Templates and Usage Guide ## Overview and Purpose The MCP Platform ships with a curated library of built-in server templates under `mcp_platform/template/templates/`. Each template wraps a real-world service (databases, code hosting platforms, ticketing systems, search engines, demos) into a deployable MCP server with consistent configuration, transport handling, and tool exposure. Templates expose `template.json` metadata alongside a FastMCP-based Python server, enabling one-command deployment via the `mcpp` CLI. The platform's core promise is "zero-configuration deployment of production-ready MCP servers with Docker containers" (Source: [README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/README.md)), and the template system is the mechanism that delivers it. Discovery, instantiation, and registration of templates are handled by the `TemplateDiscovery` and `TemplateCreator` classes exposed from the package entry point (Source: [mcp_platform/template/utils/__init__.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/__init__.py)). ## Template Architecture A template follows a modular layout: a `config.py` (typed config + env mapping), a `tools.py` (FastMCP tool definitions), and a `server.py` entrypoint. The `demo` template documents this structure explicitly, noting that the modular design makes each module "testable, maintainable, extensible, reusable" (Source: [mcp_platform/template/templates/demo/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md)). ```mermaid flowchart LR A[mcpp CLI] --> B[TemplateDiscovery] B --> C[Template Catalog] C --> D[config.py] C --> E[tools.py] C --> F[server.py] D --> G[FastMCP Server] E --> G F --> G G --> H[Docker Container] G --> I[stdio Transport] G --> J[HTTP/SSE Transport] H --> K[MCP Client / LLM] I --> K J --> K ``` `TemplateDiscovery` enumerates all templates under the `TEMPLATES_DIR` constant, while `TemplateCreator` generates new templates from a `config.py` base, scaffolding a directory tree complete with a `Dockerfile`, `README.md`, `USAGE.md`, `docs/index.md`, and pytest suite (Source: [mcp_platform/template/utils/creation.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/creation.py)). ## Built-in Template Catalog The catalog spans demos, developer platforms, ticketing, search, and databases. The community has been actively extending this list — feature requests exist for Snowflake, Trino, Elasticsearch, BigQuery, and a Postgres-based Snowflake replica, reflecting user demand for broader enterprise data coverage (Source: GitHub issues #24, #33, #36, #41). | Template | Primary Domain | Notable Capabilities | Source | |----------|----------------|----------------------|--------| | `demo` | Reference | Greeting tools, override demonstration, FastMCP HTTP-first | [demo/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md) | | `github` | Code Hosting | 77 tools covering repos, branches, issues, PRs, Actions, security | [github/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/github/README.md) | | `gitlab` | Code Hosting | 66+ tools for repos, issues, MRs, pipelines, wiki, milestones | [gitlab/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/gitlab/README.md) | | `zendesk` | Support | Ticket CRUD, user mgmt, knowledge base, analytics, orgs | [zendesk/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/zendesk/README.md) | | `postgres`, `trino`, `bigquery`, `elasticsearch` | Databases / Search | Shipped in releases 1.2.0 and 1.3.0 | Release notes in repository | ### Demo Template Usage The demo template is the canonical example. It exposes three tools — `say_hello`, `get_server_info`, and `echo_message` — and demonstrates both CLI and override-driven configuration (Source: [mcp_platform/template/templates/demo/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md)). Local usage: ```bash pip install -r requirements.txt python server.py --hello-from "Custom Server" --log-level debug python server.py --transport stdio ``` Docker usage binds port `7071` by default and can join the `mcp-platform` network for multi-container deployments. ### GitHub Template Usage The GitHub template wraps the official GitHub MCP server and exposes 77 tools grouped into repository, branch, issue, PR, Actions, and security categories. It emphasizes "dynamic tool discovery, comprehensive monitoring, auto-scaling, configuration management, and security" (Source: [mcp_platform/template/templates/github/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/github/README.md)). Users authenticate via GitHub tokens passed through the `env` block in their MCP client configuration. ### GitLab Template Usage The GitLab template supports `stdio`, SSE, and Streamable HTTP transports, plus a read-only mode (`GITLAB_READ_ONLY_MODE=true`) and feature toggles such as `USE_GITLAB_WIKI`, `USE_MILESTONE`, and `USE_PIPELINE` for granular capability control (Source: [mcp_platform/template/templates/gitlab/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/gitlab/README.md)). Self-hosted GitLab Enterprise requires setting `GITLAB_API_URL` and optionally `HTTP_PROXY`. ## Template Lifecycle and CLI Integration The interactive CLI (`mcpp`) provides session-level commands for browsing templates, listing tools, and calling them. It requires readline for command history and tab completion and lazily imports `typer`, `rich`, and `MCPClient` to keep startup fast (Source: [mcp_platform/cli/interactive_cli.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/interactive_cli.py)). Note that the previous "select template for session" injection logic has been removed — commands now require an explicit template argument to avoid ambiguity. Creating a new template from scratch is interactive: ```bash mcpp create my-template ``` The `TemplateCreator.create_template_interactive` method walks the user through id, name, description, image, capabilities, and config schema, then writes `template.json`, `config.py`, `tools.py`, `server.py`, `Dockerfile`, `README.md`, `USAGE.md`, and `docs/index.md` (Source: [mcp_platform/template/utils/creation.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/creation.py)). It generates a class name like `MyTemplateServerConfig` from the kebab-case id and stamps `metadata`, `env_mapping`, and `required` fields directly from the gathered schema. ## Common Failure Modes and Community Notes Several recurring community pain points surface around templates: - **Documentation inconsistency** — Per-template `docs/` directories have historically differed in usage instructions (Source: GitHub issue #28). The `TemplateCreator` now generates `docs/index.md` from a shared layout to standardize the contract. - **Incorrect tool-call examples** — Older BigQuery docs showed raw HTTP-style calls rather than the `mcpp` client flow; this is addressed by routing all examples through `client.call` (Source: GitHub issue #27, see [mcp_platform/template/templates/demo/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md) for the canonical pattern). - **Docs build failures** — The GitHub Actions `build-docs` workflow has been observed failing on shallow clones (Source: GitHub issue #43); this affects CI only and not runtime behavior. - **Extending to new data sources** — Community requests consistently follow the same pattern: replicate an existing template's directory layout, map authentication env vars, and add a `template.json` entry (Source: GitHub issues #24, #33, #36, #41). For advanced troubleshooting, the demo template documents debug logging via `MCP_LOG_LEVEL=debug`, port conflicts (`python server.py --port 7072`), and Docker network creation (`docker network create mcp-platform`) (Source: [mcp_platform/template/templates/demo/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md)). ## See Also - [README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/README.md) — Top-level project overview and migration from `mcp-templates`. - [mcp_platform/template/utils/creation.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/creation.py) — Reference for authoring new templates. - [mcp_platform/cli/interactive_cli.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/interactive_cli.py) — Interactive `mcpp>` shell internals. - Release notes for `release-pypi-1.1.0` through `release-pypi-1.3.1` — Per-template changelog. --- ## Creating Custom Templates and Extensions ### Related Pages Related topics: [Built-in Server Templates and Usage Guide](#page-builtin-templates), [Deployment Backends, Configuration Flow, and Client API](#page-deployment-and-client)
Related Source Files The following source files were used to generate this page: - [mcp_platform/template/utils/__init__.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/__init__.py) - [mcp_platform/template/utils/creation.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/creation.py) - [mcp_platform/template/utils/discovery.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/utils/discovery.py) - [mcp_platform/template/templates/demo/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/demo/README.md) - [mcp_platform/template/templates/gitlab/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/gitlab/README.md) - [mcp_platform/template/templates/github/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/github/README.md) - [mcp_platform/template/templates/zendesk/README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/template/templates/zendesk/README.md) - [mcp_platform/client/client.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/client/client.py) - [mcp_platform/cli/interactive_cli.py](https://github.com/Data-Everything/MCP-Platform/blob/main/mcp_platform/cli/interactive_cli.py) - [README.md](https://github.com/Data-Everything/MCP-Platform/blob/main/README.md)
# Creating Custom Templates and Extensions ## Overview and Scope MCP-Platform ships a template system that lets developers package an MCP server, its configuration schema, Docker assets, and documentation into a single deployable unit. Once installed (`pip install mcp-platform`), every template becomes addressable through the unified `mcpp` CLI for operations such as `mcpp deploy