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:

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.

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.