Ershu MCP

简体中文

Ershu MCP is the authenticated Model Context Protocol endpoint for Ershu projects. It is intended for coding agents and maintainers who need to discover projects, inspect published documents and repository snapshots, search indexed source, trace project relationships, and read consumer contracts.

The service exposes 27 tools over stateless Streamable HTTP. It reads Ershu data through ershu-core instead of routing queries through the Ershu API. It does not run the Worker analysis loop or generate AI-authored documents.

Scope

Ershu MCP provides:

• project and repository discovery;
• document, section, repository tree, and code-index navigation;
• bounded source reads after a path has been identified;
• indexed search, internal API lookup, project graph queries, change-surface discovery, and static runtime-flow tracing;
• source-derived consumer contract, public interface, and schema reads;
• queued refreshes for repository trees, code indexes, search indexes, and knowledge graphs.

The service does not create projects, repositories, users, or MCP keys. It also does not replace source inspection. Search and graph responses can be partial, stale, or truncated, and published prose can be secondary evidence.

How it fits into Ershu

MCP client
    |
    | Streamable HTTP + Bearer token
    v
ershu-mcp
    |
    +-- ershu-core services and schemas
    +-- shared PostgreSQL data
    +-- repository cache
    +-- Milvus-backed retrieval when configured

ershu-mcp depends on ershu-core. It does not import or call ershu-api or ershu-worker. A full Ershu installation combines the independently versioned components in the ershu deployment repository.

Requirements

• Python 3.14 or newer
• uv
• PostgreSQL with the Ershu schema
• Git when the service needs to read remote repositories
• Milvus for semantic retrieval; search responses report when they use a weaker fallback

Installation

Install the MCP server as part of a tested component set through the ershu installer package:

pip install "ershu[mcp]"

Projects that depend on the MCP package directly can pin the component with UV:

uv add "ershu-mcp==1.0.0.post20260812"

For development from a source checkout:

uv sync --locked
cp .env.example .env

The sample environment file contains public placeholders. Replace SECRET_KEY, ENCRYPTION_KEY, and MCP_KEY_PEPPER before starting the service. Each value must contain at least 32 characters, and the three values must differ.

Minimal startup

Apply the shared database migrations, then start the MCP process:

uv run ershu-db upgrade head
uv run ershu-mcp

The development defaults listen on 127.0.0.1:8001:

• health check: http://127.0.0.1:8001/health
• MCP endpoint: http://127.0.0.1:8001/mcp/

curl -fsS http://127.0.0.1:8001/health

A healthy process returns:

{"status":"ok"}

The health route is public. It confirms that the process is running, but it does not verify credentials, project access, repository freshness, or search availability.

Authentication

Every MCP tool call requires an HTTP Bearer token:

Authorization: Bearer <MCP key or user access token>

MCP keys inherit a user identity and can be restricted to selected projects. Invalid, expired, or revoked credentials are rejected. This package has no command for creating keys, so obtain credentials from an Ershu installation before connecting a client.

Do not put credentials in this README, committed client configuration, container images, or shell history.

Configuration

McpSettings reads .env from the current working directory. The full public example is in .env.example. The main groups are:

Group	Variables	Purpose
Runtime	ENVIRONMENT, LOG_LEVEL, MCP_HOST, MCP_PORT	Process mode, logging, and listener
Proxy	PROXY_HEADERS, FORWARDED_ALLOW_IPS	Trusted forwarded request metadata
Database	DATABASE_URL, DATABASE_POOL_SIZE, DATABASE_MAX_OVERFLOW, DATABASE_POOL_TIMEOUT_SECONDS	Shared Ershu database connection
Secrets	SECRET_KEY, ENCRYPTION_KEY, MCP_KEY_PEPPER	Token, stored credential, and MCP key protection
Retrieval	MILVUS_URI, MILVUS_TOKEN, MILVUS_DB_NAME	Semantic index access
Repository access	REPOSITORY_STORAGE_PATH, TRUSTED_LOCAL_PATHS, GIT_ALLOWED_HOSTS	Cache location and repository allowlists
Git policy	ALLOW_DEV_OPEN_LOCAL_REPOSITORY_PATHS, ALLOW_INSECURE_GIT_URLS, ALLOW_FILE_GIT_URLS, GIT_COMMAND_TIMEOUT_SECONDS	Local and remote repository safety limits
Git credentials	GITHUB_TOKEN, GITLAB_TOKEN	Optional fallback credentials for private remotes
Build identity	MCP_BUILD_COMMIT	Exact source commit used for the running process
HTTP safety	MCP_ENABLE_DNS_REBINDING_PROTECTION, MCP_ALLOWED_HOSTS, MCP_ALLOWED_ORIGINS	Streamable HTTP host and origin checks

Production mode adds these startup checks:

• MCP_BUILD_COMMIT is a full 40-character Git commit;
• installed ershu-mcp package metadata is available;
• DNS rebinding protection is enabled;
• allowed host and origin lists are not empty;
• development access to untrusted local repository paths remains disabled.

When a reverse proxy is used, keep the /mcp/ path intact and set the proxy, host, and origin allowlists to the deployed values.

Public tools

The running process is the source of truth for the tool list. Call get_server_info to read its package version, build commit, identity status, and registered capabilities.

Area	Tools
Identity and discovery	get_server_info, list_projects, resolve_project, list_project_repositories
Documents	get_project_overview, list_repository_documents, list_document_sections, get_document_section, get_document
Repository navigation	list_repository_tree, list_repository_code_index, read_code_context
Search and relationships	search_project_context, query_internal_api, query_project_graph, find_project_change_surface, trace_project_runtime_flow
Consumer contracts	list_project_contracts, get_consumer_contract, list_public_interfaces, get_public_interface, get_contract_schema, query_consumer_contracts, diff_consumer_contracts, suggest_consumer_work
Fact refresh	refresh_repository_facts, get_run_status

refresh_repository_facts requires project management permission. It queues deterministic updates for the repository tree, code index, search index, and knowledge graph. It never requests an AI document rewrite. Use get_run_status with the returned run ID to follow the work.

Recommended reading flow

1. Call get_server_info and verify the running version and build commit.
2. Discover a project with list_projects, then confirm it with resolve_project.
3. Use list_project_repositories to compare repository revisions and data status.
4. Read get_project_overview, then open document summaries, sections, and full documents only as needed.
5. Browse the repository tree and code index before requesting a bounded source snippet.
6. Use search, graph, change-surface, or runtime-flow tools to find candidate evidence.
7. For public interfaces, prefer structured contracts and schemas over prose.

Project references accept a UUID, slug, or exact readable project name. Use discovery instead of guessing a generic name.

Evidence and freshness

Check response metadata before treating a result as current or complete:

• authority=source_derived identifies structured source facts. authority=secondary and usage=reference_only identify navigation material that still needs source verification.
• revision_status=current means the item matches the latest known repository revision. A stale or unknown status is only a lead.
• data_status, result_status, warnings, verification_required, and next_actions explain whether an empty or partial result is trustworthy.
• truncated=true means the response is not a complete list.

For paged repository trees, keep every page on the same revision. Pass the first page's workspace_commit_sha as commit_sha for a clean Git workspace, or pass tree_revision for an unversioned or dirty local workspace.

Repository access

Remote repositories are prepared under REPOSITORY_STORAGE_PATH. Limit remote access with GIT_ALLOWED_HOSTS; insecure Git URLs and file:// URLs are disabled by default. Repository-specific credentials take precedence over the optional GitHub or GitLab fallback token.

Local repository paths refer to storage visible to the MCP process. In production, add each allowed root to TRUSTED_LOCAL_PATHS and keep ALLOW_DEV_OPEN_LOCAL_REPOSITORY_PATHS=false.

Development

The package keeps MCP transport, authentication, navigation, response compaction, and refresh requests in src/ershu/mcp/. Shared data models and query services come from ershu-core.

Run the repository checks with uv:

uv run pytest -q
uv run ruff check src tests
uv run ruff format --check src tests
uv build --no-sources --out-dir dist

The tests run without the API, Worker, or deployment repository source trees.

License

Ershu MCP is licensed under the Apache License 2.0.