Metadata-Version: 2.5
Name: ershu-mcp
Version: 1.0.0.post20260812
Summary: MCP context service for Ershu.
Project-URL: Documentation, https://ershu.org
Project-URL: Repository, https://github.com/ershu-lab/ershu-mcp
Project-URL: Issues, https://github.com/ershu-lab/ershu-mcp/issues
Author: Ershu contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: code-intelligence,ershu,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.14
Requires-Dist: ershu-core<2.0.0,>=1.0.1.post20260812
Requires-Dist: fastapi<1.0.0,>=0.115.0
Requires-Dist: mcp<2.0.0,>=1.12.4
Requires-Dist: pydantic<3.0.0,>=2.10.0
Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0.36
Requires-Dist: starlette<1.0.0,>=0.37.2
Requires-Dist: uvicorn[standard]<1.0.0,>=0.34.0
Description-Content-Type: text/markdown

# Ershu MCP

[简体中文](README-CN.md)

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

```text
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](https://docs.astral.sh/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](https://github.com/ershu-lab/ershu):

```bash
pip install "ershu[mcp]"
```

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

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

For development from a source checkout:

```bash
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:

```bash
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/`

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

A healthy process returns:

```json
{"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:

```text
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`](.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:

```bash
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](LICENSE).
