Metadata-Version: 2.5
Name: harborrag-mcp-server
Version: 2.0.0a2
Summary: MCP facade and audited tools for HarborRAG.
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: fastmcp<5,>=4.1.2
Requires-Dist: harborrag-core==2.0.0a2
Requires-Dist: harborrag-engine==2.0.0a2
Requires-Dist: harborrag-runtime==2.0.0a2
Requires-Dist: jsonschema<5,>=4.26
Requires-Dist: pydantic<3,>=2.12
Requires-Dist: python-dotenv<2,>=1
Requires-Dist: pyyaml<7,>=6.0.2
Provides-Extra: mcp
Provides-Extra: reader
Requires-Dist: harborrag-runtime[reader]==2.0.0a2; extra == 'reader'
Provides-Extra: ui
Requires-Dist: fastmcp[apps]<5,>=4.1.2; extra == 'ui'
Description-Content-Type: text/markdown

# harborrag-mcp-server

Owns the FastMCP transport, pre-execution policy, and durable audit boundary.

## Folder ownership

```text
__main__.py                 stdio / HTTP launcher and flag parsing
server/base.py              server protocol
server/server.py            tool registry, policy enforcement, dispatch
server/http.py              loopback Streamable HTTP transport and status UI
server/http_auth.py         owner-only bearer and tenant authorization
server/static/status.html   status page and Tool Playground
server/explorer/            HarborRAG Explorer MCP App served by harborrag-mcp-ui
configuration/              config/mcp.yaml loading, validation, env overrides
policy.py                   compiled safety ceilings
audit.py                    JSONL audit writer
defaults/mcp.yaml           packaged fallback configuration
```

The 11 reader tool implementations, schemas, catalog, and checked dispatcher live
in `harborrag_engine.tools`. Generic contracts live in `harborrag_core`.
`harborrag_runtime.composition.readers` connects the reader backends and owns
their lifecycle. MCP adapts authentication, registration, configuration, and
protocol responses; the optional agent uses the same dispatcher.

## Team deliverables

- The shipped transport exposes the eleven read-only tools documented in
  [MCP Tools](../../docs/users/detailed-guides/mcp-server/README.md):
  evidence search/fetch/context, source discovery, static graph description, bounded
  triplet/subgraph/path traversal, exact graph-node resolution, document
  inventory, and faceted entity ranking.
  Chat and agent are not MCP tools; they are served only through the HarborRAG
  REST API's `/v1/chat/completions` and `/v1/agent/completions` endpoints.
- Every attempt and outcome is durably audited with a principal identifier and
  arguments digest; raw arguments and tokens are never recorded.
- Shared reader execution outcomes are recorded separately by the runtime at
  `~/.harborrag/tool-execution-audit.jsonl`; set
  `HARBORRAG_TOOL_EXECUTION_AUDIT_PATH` to choose another path. The invocation
  identifier correlates execution records with MCP transport records.
- Declared input schemas plus argument, result-count, and serialized-output
  budgets are enforced.
- Ingestion-capability tools fail closed until explicitly enabled.
- Transport creation fails closed without authentication unless the caller
  explicitly selects local unauthenticated stdio.
- Service-level tools must never expose raw database/provider access or place
  retrieved document text in descriptions.

Install the reader profile before running the launcher. Reader serving connects
the configured database, object store, vector store, graph store, and embedding
client. It does not start conversation memory, chat, an agent, or an ingestion
executor, and it does not provision object-store buckets:

```bash
uv sync --package harborrag-mcp-server --extra reader
```

Run the standard stdio transport from a checkout:

```bash
scripts/deployment/mcp.sh
```

Build the equivalent non-root container and verify its advertised registry:

```bash
docker build -f deploy/docker/Dockerfile.mcp -t harborrag-mcp .
docker run --rm harborrag-mcp --check
```

For a real stdio MCP session, run the image with an attached stdin, the
database/model environment files, and connectivity to the configured data
services. The image entrypoint is `python -m harborrag_mcp_server`, so MCP
arguments such as `--check` or `--transport http` are forwarded directly.

`harborrag-mcp` is the canonical installed command. It accepts `--env-file`
for deployment settings; the checkout script only selects Python and passes
`--local-stack-root` to translate local database/model/MCP env files. Neither
path loads API settings or executes env files as shell code. The command
constructs the reader application and communicates over stdin/stdout.
It is a child process launched by an MCP client, not an interactive terminal or
HTTP service. Run `scripts/deployment/mcp.sh --check` yourself to perform a real
MCP handshake and print the eleven advertised tool names without connecting to
providers.

Run an authenticated local Streamable HTTP endpoint and status page:

```bash
scripts/deployment/dev.sh bootstrap
scripts/deployment/dev.sh up         # data services + API, which applies the migrations
scripts/deployment/mcp.sh --http
```

The browser status page is `http://127.0.0.1:8010/`, health is available at
`http://127.0.0.1:8010/healthz`, and MCP clients connect to
`http://127.0.0.1:8010/mcp` with the token in an `Authorization: Bearer`
header. Override the loopback host, port, or path with `--host`, `--port`, and
`--path`; this local static-token mode intentionally rejects non-loopback
hosts. The bootstrap command generates the token in the Git-ignored
`env/.env.mcp` file with mode `0600`; override that path with `MCP_ENV_FILE`.

## Tool Playground

Open the browser page, enter the bearer token, provide a tenant ID, and select
**Load tools**. The page builds an argument form from the effective JSON schema
and executes the selected tool with **Run tool**. Tenant-specific enablement,
defaults and limits are applied before execution, and each attempt is audited.

Chat and agent are not part of this catalog; use the HarborRAG REST API's
`/v1/chat/completions` and `/v1/agent/completions` endpoints instead.

The owner-only browser API is:

- `GET /api/tools?tenant_id=<tenant>` for the effective catalog;
- `POST /api/tools/call` with `{"name": "...", "arguments": {...}}` to run a tool.

The API is a local administrative convenience, not a second unprotected tool
transport. It requires the same owner bearer token as configuration editing.

## Explorer MCP UI server

`harborrag-mcp-ui` is an optional second MCP server that serves only the
HarborRAG Explorer, a FastMCP 4 `FastMCPApp` whose Prefab UI helps people search
the corpus. Hosts that support MCP Apps render it, including the MCP Inspector's
**Apps** tab. The reader server works without it: its catalog is unchanged, it
never imports `server/explorer/`, and FastMCP Apps and Prefab come only from the
`ui` extra (`harborrag-mcp-server[ui]`).

In a checkout, `scripts/deployment/mcp-ui.sh` runs it in Docker from
`deploy/compose/docker-compose.mcp-ui.yml` and `deploy/docker/Dockerfile.mcp-ui`,
a thin layer over the reader image.

- `open_explorer` is the model-visible entry point and returns the UI.
- `explorer_search`, `explorer_read`, `explorer_browse` and `explorer_graph` are
  app-only backends for search, reading, browsing and graph tracing. They call
  the registered reader handlers, so authentication, tenant binding,
  configuration, budgets and audit are shared.
- Found evidence goes back to the conversation only when the user selects
  **Send to chat** or **Add to conversation context**.
- It takes the reader server's flags and environment, listens on
  `HARBORRAG_MCP_UI_PORT` (default `8011`) over HTTP, and serves `/healthz` only.
- The renderer loads from `cdn.jsdelivr.net`, declared in the resource CSP.

See [Setup and Integration](../../docs/users/detailed-guides/mcp-server/setup-and-integration.md#explorer-mcp-ui-server)
for running it and for the MCP Inspector workflow.

## Tool configuration

The versioned configuration lives at `config/mcp.yaml` by default. Set
`HARBORRAG_MCP_CONFIG_PATH` or pass `--config` after `--http` to select another
file. The configuration controls:

- global policy budgets;
- globally enabled tools;
- optional argument defaults and numeric upper limits;
- per-tenant enabled state, defaults, and limits.

Required fields and `tenant_id` can never receive defaults, unknown tools and
fields are rejected, and configured limits cannot exceed each tool's compiled
safety ceiling. Tenant IDs are canonicalized before policy lookup and execution,
and configuration tenant keys may not contain surrounding whitespace. These environment variables override the file without being
persisted back into it:

- `HARBORRAG_MCP_MAX_RESULTS`
- `HARBORRAG_MCP_MAX_ARGUMENT_BYTES`
- `HARBORRAG_MCP_MAX_OUTPUT_BYTES`
- `HARBORRAG_MCP_DISABLED_TOOLS` (comma-separated tool names)

In HTTP mode, enter the bearer token in the status page and use **Load**,
**Save**, or **Reload YAML**. The owner-only API is `GET/PUT /api/config` and
`POST /api/config/reload`. Saves use revision checks and atomic replacement;
audit records contain only revision hashes, never configuration values.

Defaults, limits, budgets, and tenant overrides are enforced immediately.
Changes to global advertised tool schemas or enabled tools set
`restart_required=true`; restart the MCP process so connected clients receive
the new advertised catalog.

Network transports must be constructed with a FastMCP authentication provider.
MCP tool calls require an authenticated token carrying `role=owner` and an
explicit `tenants` claim containing the requested tenant. Global owners must
carry the deliberate wildcard claim `tenants=["*"]`.
The explicit local override is for stdio only and opens no listener.


## Package tests

Tests for this package live in:

```text
packages/harborrag-mcp-server/tests/
```

Run from the repository root:

```bash
pytest packages/harborrag-mcp-server/tests
```

Keep new tests in this folder when adding or changing behavior owned by this package.
