Enterprise MCP Server Template

A production-ready, transport-independent foundation for building enterprise Model Context Protocol (MCP) servers in Python.

This template contains zero business logic. It provides the infrastructure, abstractions, and tooling that every MCP server needs, so downstream projects can focus on their domain capabilities.

Template First Principle All new MCP servers must be created from this template. Generic capabilities are added to the template; server-specific capabilities remain in the individual repository. The template evolves independently, and downstream projects adopt new template versions through controlled upgrades.

---

Features

• Transport-independent core — Streamable HTTP (default), SSE, and stdio behind a single Transport abstraction. Business logic never depends on a concrete transport.
• Configuration — hierarchical loading: bundled defaults → environment YAML → environment variables → CLI overrides (Pydantic v2 + YAML).
• Dependency injection — small, testable async-capable DI container.
• Structured logging — structlog with JSON and console renderers.
• Event bus — async-first publish/subscribe with subscriber isolation.
• Tool framework — @tool decorator, metadata models, registry, and input validation.
• Extendable scaffolds — plugins, middleware, hooks, providers, workers, persistence, security, and AI packages with defined extension points.
• Plugin framework — minimal plugin architecture with manifest-based discovery, lifecycle hooks, and a unified PluginContext.
• Form Automation plugin — deterministic DOM-based form detection, pre-interaction validation, and structured form tools (fill, check, uncheck, select, submit).
• Observable — /health, /live, /ready, /version endpoints.
• Developer tooling — uv, Ruff, Pyright, pytest, pre-commit, Makefile.
• Operations — Docker, docker-compose, Kubernetes manifests, GitHub Actions.

Technology Stack

Concern	Choice
Python	3.13
Package manager	uv
Web framework	FastAPI
MCP SDK	Official Python MCP SDK
Validation	Pydantic v2
Config	pydantic-settings + YAML
Logging	structlog
CLI	Typer
HTTP server	Uvicorn
Testing	pytest
Async	asyncio
Lint	Ruff
Type checking	Pyright
Hooks	pre-commit
Docs	MkDocs Material
Containers	Docker
Plugins	Built-in framework
Form Automation	Deterministic DOM + Retry

Quick Start

Prerequisites: uv with Python 3.13.

uv sync --all-extras
make doctor        # verify the environment
make test          # run the test suite
make run           # start the server (http://localhost:8000)

Check the server is healthy:

curl http://localhost:8000/health
curl http://localhost:8000/ready
curl http://localhost:8000/version

CLI

uv run enterprise-mcp serve            # run the server
uv run enterprise-mcp version          # print version info
uv run enterprise-mcp doctor           # environment diagnostics
uv run enterprise-mcp config --json    # show effective configuration
uv run enterprise-mcp plugins          # list extensions (scaffold)

Repository Layout

src/enterprise_mcp/
├── foundation/     # DI container, app lifecycle, startup/shutdown
├── config/         # loaders, defaults, settings/*.yaml
├── observability/  # logging, metrics, tracing
├── security/       # auth, RBAC, secrets, audit
├── transport/      # base interface, HTTP, SSE, stdio
├── mcp/            # protocol and server abstractions
├── tools/          # decorators, metadata, loader, validator, registry
├── extensions/     # plugins, middleware, hooks, providers
├── workers/        # executors, schedulers, queues, retry
├── persistence/    # repositories, models, migrations, database
├── interfaces/     # REST, WebSocket, internal API
├── events/         # event bus
├── resources/      # templates, static, sample-data
├── utils/          # shared utilities
├── ai/             # memory, prompts, agents (reserved)
└── cli/            # Typer-based CLI

Documentation

• Architecture
• Design Principles
• Compatibility
• Development Rules
• Folder Structure
• Production Checklist
• ADR index
• Element Engine

License

MIT — see LICENSE.