nace-mcp 0.1.0__tar.gz

nace_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nace AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nace_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: nace-mcp
+Version: 0.1.0
+Summary: MCP server for the Drex API: calibrated decisions and document jobs for coding agents
+Keywords: drex,nace,mcp,model-context-protocol,document-intelligence
+Author: Nace AI
+Author-email: Nace AI <engineering@nace.ai>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: nace-sdk>=0.1,<1
+Requires-Dist: mcp>=1.28,<2
+Requires-Dist: truststore>=0.10.4,<1
+Requires-Python: >=3.11
+Project-URL: Homepage, https://console.nace.ai
+Project-URL: Documentation, https://console.nace.ai/docs/developer-tools/mcp
+Description-Content-Type: text/markdown
+
+# nace-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for the [Drex API](https://console.nace.ai/docs): coding agents get calibrated decisions and document jobs as tools. MIT; built on [`nace-sdk`](https://pypi.org/project/nace-sdk/).
+
+```bash
+nace-mcp login                           # or: uvx nace-mcp login; paste a key from https://console.nace.ai/dashboard/api-keys
+claude mcp add nace -- uvx nace-mcp      # Claude Code
+```
+
+`nace-mcp login` checks the key against Drex and saves it to `~/.nace/config.toml` (mode 0600), the file `nace login` from [`nace-cli`](https://pypi.org/project/nace-cli/) writes too, so either signs in both. `--api-key KEY` passes the key, `--api-key -` reads it from stdin; without a terminal one of them is required. `$NACE_API_KEY`, `$NACE_BASE_URL` and `$NACE_CONFIG_PATH` in the server's environment override the file. Without a key the server still starts, and every tool answers with how to sign in until one is saved. The server reads the credentials on each call, so `nace-mcp login` while it runs, to sign in or to replace a refused key, needs no restart. `nace-mcp --version` prints the server and SDK versions.
+
+## Connect an agent
+
+Codex: `codex mcp add nace -- uvx nace-mcp` (or a `[mcp_servers.nace]` table with `command = "uvx"` and `args = ["nace-mcp"]` in `~/.codex/config.toml`).
+
+OpenCode (`opencode.json`): `"mcp": {"nace": {"type": "local", "command": ["uvx", "nace-mcp"], "enabled": true}}`.
+
+Claude Desktop (`claude_desktop_config.json`) and Cursor (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "nace": {
+      "command": "uvx",
+      "args": ["nace-mcp"]
+    }
+  }
+}
+```
+
+Add `"env": {"NACE_API_KEY": "nace_sk_..."}` to pass a key without `nace-mcp login`. To install it once instead of through `uvx`: `pipx install nace-mcp` (Python 3.11 or later), then use `nace-mcp` as the command.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `decide` | Answer typed questions (`noul`, `choice`, `score`) about text or JSON with calibrated probabilities. |
+| `list_models` | List the models `decide` can use. |
+| `upload_document` | Upload a local file into the account's workspace. |
+| `parse_document` | Convert a document to Markdown, text or layout blocks. |
+| `split_document` | Cut a packet into segments, each with a class. |
+| `classify_document` | Label a document, or each page, with your classes. |
+| `extract_data` | Fill a JSON Schema, with a status and citation per field. |
+| `ground_items` | Find where each quote appears in a document. |
+| `get_job` | Read a job and a summary of its result. |
+| `wait_for_job` | Wait for a job to finish. |
+| `list_jobs` | List jobs, newest first. |
+| `cancel_job` | Cancel a running job, or drop a finished one from the list. |
+| `get_job_request` | The request a job ran under. |
+| `download_job_file` | Save a file a job produced. |
+| `get_job_rows` | Page through a parsed sheet's rows. |
+| `list_extraction_schemas` | List saved extraction schemas. |
+| `get_extraction_schema` | Read a saved schema, at its latest or a given version. |
+| `list_extraction_schema_versions` | List a saved schema's versions. |
+| `create_extraction_schema` | Save a new extraction schema. |
+| `add_extraction_schema_version` | Add a version to a saved schema. |
+| `get_documentation` | Usage notes for a topic, shipped with the server. |
+
+The document tools take one source: an `https://` `url`, a local `path` (uploaded first), an uploaded file's `workspace_id` and `file_id`, or a finished parse's `parse_job_id`. They wait up to `wait_seconds` (60 at most) and return the job; one still running comes back with an instruction to call `wait_for_job`. Any other request field goes in a tool's `options`; an argument a tool doesn't have is refused rather than ignored. Results are summarised, and text or JSON longer than `max_inline_chars` is written to a file readable only by you, whose path is returned. For a document too large to return inline, `parse_document` saves the full Markdown to a file.
+
+Full documentation: [MCP server](https://console.nace.ai/docs/developer-tools/mcp).

nace_mcp-0.1.0/README.md

@@ -0,0 +1,61 @@
+# nace-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for the [Drex API](https://console.nace.ai/docs): coding agents get calibrated decisions and document jobs as tools. MIT; built on [`nace-sdk`](https://pypi.org/project/nace-sdk/).
+
+```bash
+nace-mcp login                           # or: uvx nace-mcp login; paste a key from https://console.nace.ai/dashboard/api-keys
+claude mcp add nace -- uvx nace-mcp      # Claude Code
+```
+
+`nace-mcp login` checks the key against Drex and saves it to `~/.nace/config.toml` (mode 0600), the file `nace login` from [`nace-cli`](https://pypi.org/project/nace-cli/) writes too, so either signs in both. `--api-key KEY` passes the key, `--api-key -` reads it from stdin; without a terminal one of them is required. `$NACE_API_KEY`, `$NACE_BASE_URL` and `$NACE_CONFIG_PATH` in the server's environment override the file. Without a key the server still starts, and every tool answers with how to sign in until one is saved. The server reads the credentials on each call, so `nace-mcp login` while it runs, to sign in or to replace a refused key, needs no restart. `nace-mcp --version` prints the server and SDK versions.
+
+## Connect an agent
+
+Codex: `codex mcp add nace -- uvx nace-mcp` (or a `[mcp_servers.nace]` table with `command = "uvx"` and `args = ["nace-mcp"]` in `~/.codex/config.toml`).
+
+OpenCode (`opencode.json`): `"mcp": {"nace": {"type": "local", "command": ["uvx", "nace-mcp"], "enabled": true}}`.
+
+Claude Desktop (`claude_desktop_config.json`) and Cursor (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "nace": {
+      "command": "uvx",
+      "args": ["nace-mcp"]
+    }
+  }
+}
+```
+
+Add `"env": {"NACE_API_KEY": "nace_sk_..."}` to pass a key without `nace-mcp login`. To install it once instead of through `uvx`: `pipx install nace-mcp` (Python 3.11 or later), then use `nace-mcp` as the command.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `decide` | Answer typed questions (`noul`, `choice`, `score`) about text or JSON with calibrated probabilities. |
+| `list_models` | List the models `decide` can use. |
+| `upload_document` | Upload a local file into the account's workspace. |
+| `parse_document` | Convert a document to Markdown, text or layout blocks. |
+| `split_document` | Cut a packet into segments, each with a class. |
+| `classify_document` | Label a document, or each page, with your classes. |
+| `extract_data` | Fill a JSON Schema, with a status and citation per field. |
+| `ground_items` | Find where each quote appears in a document. |
+| `get_job` | Read a job and a summary of its result. |
+| `wait_for_job` | Wait for a job to finish. |
+| `list_jobs` | List jobs, newest first. |
+| `cancel_job` | Cancel a running job, or drop a finished one from the list. |
+| `get_job_request` | The request a job ran under. |
+| `download_job_file` | Save a file a job produced. |
+| `get_job_rows` | Page through a parsed sheet's rows. |
+| `list_extraction_schemas` | List saved extraction schemas. |
+| `get_extraction_schema` | Read a saved schema, at its latest or a given version. |
+| `list_extraction_schema_versions` | List a saved schema's versions. |
+| `create_extraction_schema` | Save a new extraction schema. |
+| `add_extraction_schema_version` | Add a version to a saved schema. |
+| `get_documentation` | Usage notes for a topic, shipped with the server. |
+
+The document tools take one source: an `https://` `url`, a local `path` (uploaded first), an uploaded file's `workspace_id` and `file_id`, or a finished parse's `parse_job_id`. They wait up to `wait_seconds` (60 at most) and return the job; one still running comes back with an instruction to call `wait_for_job`. Any other request field goes in a tool's `options`; an argument a tool doesn't have is refused rather than ignored. Results are summarised, and text or JSON longer than `max_inline_chars` is written to a file readable only by you, whose path is returned. For a document too large to return inline, `parse_document` saves the full Markdown to a file.
+
+Full documentation: [MCP server](https://console.nace.ai/docs/developer-tools/mcp).

nace_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "nace-mcp"
+version = "0.1.0"
+description = "MCP server for the Drex API: calibrated decisions and document jobs for coding agents"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "drex",
+    "nace",
+    "mcp",
+    "model-context-protocol",
+    "document-intelligence",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "nace-sdk>=0.1,<1",
+    "mcp>=1.28,<2",
+    "truststore>=0.10.4,<1",
+]
+
+[[project.authors]]
+name = "Nace AI"
+email = "engineering@nace.ai"
+
+[project.urls]
+Homepage = "https://console.nace.ai"
+Documentation = "https://console.nace.ai/docs/developer-tools/mcp"
+
+[project.scripts]
+nace-mcp = "nace_mcp._entrypoint:main"
+
+[tool.uv.sources.nace-sdk]
+workspace = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 150
+fix = true
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "B",
+    "UP",
+    "RUF",
+    "ASYNC",
+    "SIM",
+    "BLE",
+    "PLC0415",
+]
+ignore = [
+    "D",
+    "ANN",
+    "PLR0913",
+    "ASYNC109",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [
+    "src",
+    "tests",
+]
+asyncio_mode = "auto"
+addopts = [
+    "--strict-markers",
+    "--tb=short",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.12.0"]
+build-backend = "uv_build"

nace_mcp-0.1.0/pyproject.toml.orig

@@ -0,0 +1,67 @@
+[project]
+name = "nace-mcp"
+version = "0.1.0"
+description = "MCP server for the Drex API: calibrated decisions and document jobs for coding agents"
+authors = [
+    { name = "Nace AI", email = "engineering@nace.ai" }
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "drex",
+    "nace",
+    "mcp",
+    "model-context-protocol",
+    "document-intelligence",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "nace-sdk>=0.1,<1",
+    "mcp>=1.28,<2",
+    "truststore>=0.10.4,<1",
+]
+
+[project.urls]
+Homepage = "https://console.nace.ai"
+Documentation = "https://console.nace.ai/docs/developer-tools/mcp"
+
+[project.scripts]
+nace-mcp = "nace_mcp._entrypoint:main"
+
+[tool.uv.sources]
+nace-sdk = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 150
+fix = true
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "RUF", "ASYNC", "SIM", "BLE", "PLC0415"]
+ignore = [
+    "D",
+    "ANN",
+    "PLR0913",
+    "ASYNC109",  # `timeout` on wait_for_job is a polling budget, not a cancel scope
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]
+asyncio_mode = "auto"
+addopts = ["--strict-markers", "--tb=short"]

nace_mcp-0.1.0/src/nace_mcp/__init__.py

@@ -0,0 +1,12 @@
+"""``nace-mcp`` — an MCP server for the Drex API, for coding agents.
+
+Decisions (``POST /v1/systemone``), document jobs and uploads (``/v1/documents/*``)
+and saved extraction schemas (``/v1/extraction-schemas``) over ``nace-sdk``, served
+over stdio. Credentials come from ``$NACE_API_KEY`` / ``$NACE_BASE_URL`` or
+``~/.nace/config.toml`` (``nace-mcp login`` or ``nace login``).
+"""
+
+from nace_mcp._version import __version__
+from nace_mcp.server import build_server
+
+__all__ = ["__version__", "build_server"]

nace_mcp-0.1.0/src/nace_mcp/_cli.py

@@ -0,0 +1,97 @@
+"""``nace-mcp`` entry point: serve over stdio, ``login`` to save a key, ``--version``.
+
+While serving, stdout is the MCP protocol channel: nothing else may print there.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from getpass import getpass
+
+from nace_sdk import NaceAPIConnectionError, NaceAPIError
+from nace_sdk import __version__ as sdk_version
+from nace_sdk.constants import BASE_URL_ENV, DEFAULT_BASE_URL, read_env
+from nace_sdk.credentials import CredentialsError, config_path, login, read_config
+
+from nace_mcp import __version__, build_server
+from nace_mcp._run import describe_api_error
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nace-mcp",
+        description=(
+            "Nace MCP server for coding agents, over stdio. Credentials come from $NACE_API_KEY / $NACE_BASE_URL "
+            "or ~/.nace/config.toml (`nace-mcp login` or `nace login`)."
+        ),
+    )
+    parser.add_argument("--version", dest="show_version", action="store_true", help="Print nace-mcp and nace-sdk versions.")
+    sub = parser.add_subparsers(dest="command")
+    login_p = sub.add_parser("login", help="Check an API key against Drex and save it to ~/.nace/config.toml (the file `nace login` uses).")
+    login_p.add_argument(
+        "--api-key",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="KEY",
+        help="The nace_sk_ key; --api-key - reads it from stdin. Omit KEY to type it hidden at a terminal.",
+    )
+    return parser
+
+
+def read_key(value: str | None) -> str:
+    """The key to save: ``KEY`` itself, ``-`` from stdin, else typed hidden at a terminal."""
+    if value == "-":
+        return getpass("Drex API key: ") if sys.stdin.isatty() else sys.stdin.readline()
+    if value:
+        return value
+    if not sys.stdin.isatty():
+        raise CredentialsError("pass --api-key KEY (or --api-key - to read stdin) when not in a terminal")
+    return getpass("Drex API key: ")
+
+
+def login_base_url() -> str:
+    """The host ``login`` checks the key against, as :func:`nace_sdk.credentials.login` picks it."""
+    return read_env(BASE_URL_ENV) or read_config(config_path(), recover=True).get("base_url") or DEFAULT_BASE_URL
+
+
+def run_login(api_key: str | None) -> int:
+    try:
+        path = login(read_key(api_key))
+    except CredentialsError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except NaceAPIError as exc:
+        print(f"error: {describe_api_error(exc)}", file=sys.stderr)
+        return 1
+    except NaceAPIConnectionError as exc:
+        # A person reads this, not an agent: name the host, which a typo in $NACE_BASE_URL makes unreachable.
+        print(
+            f"error: could not reach {login_base_url()}: {str(exc).rstrip('.')}. Check ${BASE_URL_ENV} "
+            f"(else base_url in {config_path()}) and your network; nothing was saved.",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"saved API key to {path}", file=sys.stderr)
+    return 0
+
+
+def run_version() -> int:
+    print(f"nace-mcp {__version__}")
+    print(f"nace-sdk {sdk_version}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.show_version:
+        return run_version()
+    if args.command == "login":
+        return run_login(args.api_key)
+    build_server().run(transport="stdio")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nace_mcp-0.1.0/src/nace_mcp/_decide.py

@@ -0,0 +1,98 @@
+"""Decision tools: ``decide`` (``POST /v1/systemone``) and ``list_models``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+from nace_sdk import AsyncNaceClient, Choice, NaceError, Noul, Question, Score, SystemOneResponse
+from pydantic import ValidationError
+
+from nace_mcp._run import GetClient, run_tool
+
+#: decide has no idempotency key: a request that reached Drex was answered and billed.
+DECIDE_RETRY = "Calling decide again is safe, but if this request reached Drex it was billed, and the new one is billed too."
+
+QUESTION_TYPES: dict[str, type[Noul] | type[Choice] | type[Score]] = {"noul": Noul, "choice": Choice, "score": Score}
+
+
+def question_objects(questions: dict[str, Any]) -> dict[str, Question]:
+    """Each question as the SDK's ``Noul``, ``Choice`` or ``Score``, refusing an unknown type or field by name."""
+    parsed: dict[str, Question] = {}
+    for name, raw in questions.items():
+        kind = raw.get("type") if isinstance(raw, dict) else None
+        model = QUESTION_TYPES.get(kind) if isinstance(kind, str) else None
+        if model is None:
+            raise ValueError(f'question {name!r} needs "type": "noul", "choice" or "score", got {kind!r}')
+        try:
+            parsed[name] = model.model_validate(raw)
+        except ValidationError as exc:
+            problems = "; ".join(f"{'.'.join(str(part) for part in error['loc']) or 'question'}: {error['msg']}" for error in exc.errors())
+            raise ValueError(f"question {name!r} ({kind}): {problems}") from None
+    return parsed
+
+
+def _request_id(response: SystemOneResponse) -> str | None:
+    try:
+        return response.request_id
+    except NaceError:
+        return None
+
+
+def register_decide_tools(mcp: FastMCP, get_client: GetClient) -> None:
+    @mcp.tool()
+    async def decide(state: Any, questions: dict[str, dict[str, Any]], model: str | None = None) -> dict[str, Any]:
+        """Answer typed questions about a state with calibrated probabilities, in one call.
+
+        Use it for a decision about text or data: route a ticket, flag a message, grade a reply,
+        check a condition. state is the text or any JSON value the questions are about. questions
+        maps a name you choose (it keys the answer) to one question, up to 512:
+
+        - {"type": "noul", "instructions": "Is the customer asking for a refund?", "criteria"?:
+          {"true": "what counts as yes", "false": "what counts as no"}}: yes or no. Needs
+          instructions or a criterion. The answer's noul is the probability of yes, 0 to 1.
+        - {"type": "choice", "instructions"?: "What is this ticket about?", "criteria": {"billing":
+          "Payments or refunds", "technical": "Bugs or outages", "other": null}}: one label from a
+          set without order. The answer has choice, probabilities per label and confidence.
+        - {"type": "score", "instructions"?: "How upset is the customer?", "criteria": ["Calm",
+          "Annoyed", "Angry"]}: a place on an ordered scale, low to high, the index being the
+          score. The answer has score (an expected level, possibly fractional), legend,
+          probabilities per level and confidence.
+
+        Batch every question about one state into one call: the state is billed once, per input
+        token. model defaults to the server's $NACE_DEFAULT_DECISION_MODEL, else drex-latest; list_models
+        lists the others. Returns {model,
+        answers, usage, evaluation_time_ms, request_id}. Choose your own threshold on the
+        probabilities rather than treating them as a verdict.
+        """
+
+        async def op(client: AsyncNaceClient) -> dict[str, Any]:
+            response = await client.system_one(state, question_objects(questions), model=model or None)
+            return {
+                "model": response.model,
+                "answers": {name: answer.model_dump(mode="json") for name, answer in response.answers.items()},
+                "usage": response.usage.model_dump(mode="json"),
+                "evaluation_time_ms": response.evaluation_time_ms,
+                "request_id": _request_id(response),
+            }
+
+        return await run_tool(get_client, op, retry=DECIDE_RETRY)
+
+    @mcp.tool()
+    async def list_models() -> dict[str, Any]:
+        """List the decision models the account can call, for decide's model argument.
+
+        alias_for names the version an alias such as drex-latest (or a retired id) is answered by,
+        and is null for a pinned version. Works at any balance.
+        """
+
+        async def op(client: AsyncNaceClient) -> dict[str, Any]:
+            response = await client.models.list()
+            return {
+                "models": [
+                    {"name": item.name, "alias_for": item.alias_for, "release_date": item.release_date, "description": item.description}
+                    for item in response.models
+                ]
+            }
+
+        return await run_tool(get_client, op)

nace_mcp-0.1.0/src/nace_mcp/_docs.py

@@ -0,0 +1,30 @@
+"""``get_documentation``: current Drex usage, shipped with the package, not training memory."""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from typing import Any, Literal, get_args
+
+from mcp.server.fastmcp import FastMCP
+
+Topic = Literal["overview", "decide", "sources", "parse", "split", "classify", "extract", "ground", "jobs", "schemas", "errors"]
+TOPICS: tuple[str, ...] = get_args(Topic)
+
+
+def topic_text(topic: str) -> str:
+    if topic not in TOPICS:
+        raise ValueError(f"unknown topic {topic!r}; choose one of: {', '.join(TOPICS)}")
+    return files("nace_mcp").joinpath("docs").joinpath(f"{topic}.md").read_text(encoding="utf-8")
+
+
+def register_doc_tools(mcp: FastMCP) -> None:
+    @mcp.tool()
+    async def get_documentation(topic: Topic) -> dict[str, Any]:
+        """Return Drex's current usage notes for one topic, with the link to the full page.
+
+        Read overview first. Topics: overview (what each tool does, costs), decide (questions and
+        answers), sources (url, path, workspace files, parse_job_id), parse, split, classify,
+        extract, ground (each tool's options and result), jobs (waiting, files, rows, payloads and
+        spill files), schemas (saved extraction schemas), errors (what a failed call means).
+        """
+        return {"topic": topic, "text": topic_text(topic)}