AI导哈

MCP服务开发模板

mcp-template 是一个开箱即用的 Python 工程模板，基于同一套业务逻辑自动提供 CLI、MCP 服务器和 HTTP API 三种接口，适用于快速构建可部署的 AI Agent 工具和 MCP 服务。

  • by Miyamura80
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Miyamura80/MCP-Template

使用说明

mcp-template

Batteries-included Python template. One codebase ships as a CLI, an MCP server, and an HTTP API over a shared service registry.

Key Features • Architecture • Quick Start • CLI Usage • Adding Commands • Configuration • Deploy • Credits

Agent Prompt

Copy and paste this into your AI coding agent (Claude Code, Cursor, Copilot, etc.) to install:

Install the CLI and download the gmail-mcp skill:

pip install mcp-template

curl -fsSL https://raw.githubusercontent.com/Miyamura80/MCP-Template/main/scripts/install-skills.sh -o install-skills.sh
bash install-skills.sh && rm install-skills.sh

The official gmail-mcp agent skill is self-published on skills.sh. Install it directly with:

npx skills add Miyamura80/MCP-Template

The skill's source of truth lives in skills/gmail-mcp/SKILL.md; make sync-skills mirrors it to the landing page's /.well-known/agent-skills/ discovery tree (digest-pinned in index.json).

App Distribution

  • MCP server with OAuth
  • Claude connectors and ChatGPT apps
  • APIs and SDKs
  • Chat interfaces like iMessage and WhatsApp
  • A dashboard that uses the same MCP layer
  • Open source

Key Features

Feature Stack
CLI (auto-discovery commands, global flags, shell completions, self-update) Typer
MCP server (streamable HTTP at /mcp, services auto-registered as tools; stdio supported for local dev) FastMCP
HTTP API server (also hosts /mcp) FastAPI + Uvicorn
Auth WorkOS + API keys
Payments Stripe subscriptions + x402 sell-side paywall (price a tool with @service(price=...); agents pay per call in stablecoins, Cloudflare Wallets / x402 ecosystem)
Database + migrations SQLAlchemy + Alembic
Config (YAML + .env) Pydantic-settings
LLM inference + observability DSPY + LiteLLM + LangFuse
Testing pytest + TestTemplate
Lint / type / dead-code Ruff + Vulture + ty + import-linter
Pre-commit (folder size, ai-writing, agent-config sync) prek
Telemetry Anonymous, opt-out

Architecture

One codebase, three interfaces. Write business logic once in services/ and it ships as a CLI subcommand, an MCP tool, and an HTTP route - same Pydantic input/output contract everywhere.

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ src/cli/app  │  │ mcp_server/  │  │ api_server/  │   transport / interface
│  (Typer)     │  │ (FastMCP)    │  │ (FastAPI)    │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └─────────────────┼─────────────────┘
                         ▼
                 ┌───────────────┐
                 │  services/    │   pure @service functions
                 │  @service     │   (transport-agnostic)
                 └───────┬───────┘
                         ▼
                 ┌───────────────┐
                 │  models/      │   Pydantic I/O contracts
                 └───────┬───────┘
                         ▼
        ┌────────────┬───────┬────────────┬─────────────┐
        │ common/    │ db/   │ utils/llm/ │ src/utils/  │   shared infra
        │ (config)   │ (ORM) │ (DSPY)     │ (logs/theme)│
        └────────────┴───────┴────────────┴─────────────┘

MCP UI (optional)

Need elicitation, image output, or an iframe dashboard for an MCP tool? Add an opt-in enhancer in mcp_server/enhancers/. Enhancers wrap a service for the MCP transport only - the pure service stays untouched and CLI/API consumers are unaffected.

See mcp_server/MCP_UI_ARCHITECTURE.md for the full design.

Quick Start

make onboard              # interactive setup (rename, deps, env, hooks)
uv sync                   # install deps
uv run mymcp --help       # see all CLI commands
uv run mymcp greet Alice  # run a command
uv run mymcp init my_command  # scaffold a new command

uv run mymcp-serve        # start the server (HTTP API + MCP at /mcp on one port)
uv run mymcp-mcp          # legacy: stdio MCP only, for local Claude Desktop / dev

Deploy

One-click deploy to Railway or Render (backend + managed Postgres, migrations run automatically). See deployment docs for the per-platform setup, the Railway template variable map, and OAuth/secret wiring.

CLI Usage

Global flags go before the subcommand:

Flag Short Description
--verbose -v Increase output verbosity
--quiet -q Suppress non-essential output
--debug Show full tracebacks on error
--format -f Output format: table, json, plain
--dry-run Preview actions without executing
--version -V Print version and exit 
uv run mymcp --format json config show     # JSON output
uv run mymcp --dry-run greet Bob           # preview without executing
uv run mymcp --verbose greet Alice         # detailed output

Adding Commands

Drop a Python file in src/cli/commands/ and it is auto-discovered.

Single command - export a main() function:

# src/cli/commands/hello.py
from typing import Annotated
import typer


def main(name: Annotated[str, typer.Argument(help="Who to greet.")]) -> None:
    """Say hello."""
    typer.echo(f"Hello, {name}!")

uv run mymcp hello World   # Hello, World!

Subcommand group - export app = typer.Typer():

# src/cli/commands/db.py
import typer

app = typer.Typer()


@app.command()
def migrate() -> None:
    """Run migrations."""
    ...

uv run mymcp db migrate

Or scaffold with: uv run mymcp init my_command --desc "Does something".

Configuration

from common import global_config

# Access config values from common/global_config.yaml
global_config.example_parent.example_child

# Access secrets from .env
global_config.OPENAI_API_KEY

CLI config inspection:

uv run mymcp config show                           # full config
uv run mymcp config get llm_config.cache_enabled   # single value
uv run mymcp config set logging.verbose false      # write override

Full configuration docs

Credits

This software uses the following tools:

About the Core Contributors

Made with contrib.rocks.

相关 MCP