ndi-mcp 0.1.0__tar.gz

ndi_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.

ndi_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: ndi-mcp
+Version: 0.1.0
+Summary: MCP server for NDI (Nace Document Intelligence)
+Keywords: ndi,mcp,document-intelligence,model-context-protocol
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: ndi-sdk>=0.7,<1
+Requires-Dist: mcp>=1.28,<2
+Requires-Python: >=3.11, <3.14
+Project-URL: Homepage, https://github.com/nace-ai/audit-app/tree/main/sdk/ndi-mcp
+Project-URL: Repository, https://github.com/nace-ai/audit-app
+Project-URL: Changelog, https://github.com/nace-ai/audit-app/blob/main/sdk/ndi-mcp/CHANGELOG.md
+Project-URL: Issues, https://github.com/nace-ai/audit-app/issues
+Description-Content-Type: text/markdown
+
+# NDI MCP
+
+Local and hosted [Model Context Protocol](https://modelcontextprotocol.io) servers
+for **NDI** (Nace Document Intelligence). Licensed **MIT**.
+
+```bash
+pip install ndi-mcp
+# or
+uvx ndi-mcp login
+uvx ndi-mcp
+```
+
+Depends on the Apache-2.0 [`ndi-sdk`](https://pypi.org/project/ndi-sdk/) client.
+Install and agent config details live in that package's README; prefer
+`uvx ndi-mcp` over the older `ndi-sdk[mcp]` install string.

ndi_mcp-0.1.0/README.md

@@ -0,0 +1,15 @@
+# NDI MCP
+
+Local and hosted [Model Context Protocol](https://modelcontextprotocol.io) servers
+for **NDI** (Nace Document Intelligence). Licensed **MIT**.
+
+```bash
+pip install ndi-mcp
+# or
+uvx ndi-mcp login
+uvx ndi-mcp
+```
+
+Depends on the Apache-2.0 [`ndi-sdk`](https://pypi.org/project/ndi-sdk/) client.
+Install and agent config details live in that package's README; prefer
+`uvx ndi-mcp` over the older `ndi-sdk[mcp]` install string.

ndi_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "ndi-mcp"
+version = "0.1.0"
+description = "MCP server for NDI (Nace Document Intelligence)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11,<3.14"
+keywords = [
+    "ndi",
+    "mcp",
+    "document-intelligence",
+    "model-context-protocol",
+]
+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",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "ndi-sdk>=0.7,<1",
+    "mcp>=1.28,<2",
+]
+
+[[project.authors]]
+name = "Nace AI"
+email = "engineering@nace.ai"
+
+[project.urls]
+Homepage = "https://github.com/nace-ai/audit-app/tree/main/sdk/ndi-mcp"
+Repository = "https://github.com/nace-ai/audit-app"
+Changelog = "https://github.com/nace-ai/audit-app/blob/main/sdk/ndi-mcp/CHANGELOG.md"
+Issues = "https://github.com/nace-ai/audit-app/issues"
+
+[project.scripts]
+ndi-mcp = "ndi_mcp._cli:main"
+
+[tool.uv.sources.ndi-sdk]
+workspace = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 130
+fix = true
+
+[tool.ruff.lint]
+ignore = [
+    "D",
+    "ANN",
+    "PLR0913",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+addopts = [
+    "--strict-markers",
+    "--tb=short",
+]
+
+[dependency-groups]
+dev = [
+    "pyrefly>=1.0.0,<2",
+    "pytest>=8.4.0",
+    "pytest-asyncio>=1.0.0",
+    "ruff>=0.12.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"

ndi_mcp-0.1.0/pyproject.toml.orig

@@ -0,0 +1,73 @@
+[project]
+name = "ndi-mcp"
+version = "0.1.0"
+description = "MCP server for NDI (Nace Document Intelligence)"
+authors = [
+    { name = "Nace AI", email = "engineering@nace.ai" }
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11,<3.14"
+keywords = [
+    "ndi",
+    "mcp",
+    "document-intelligence",
+    "model-context-protocol",
+]
+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",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "ndi-sdk>=0.7,<1",
+    "mcp>=1.28,<2",
+]
+
+[project.urls]
+Homepage = "https://github.com/nace-ai/audit-app/tree/main/sdk/ndi-mcp"
+Repository = "https://github.com/nace-ai/audit-app"
+Changelog = "https://github.com/nace-ai/audit-app/blob/main/sdk/ndi-mcp/CHANGELOG.md"
+Issues = "https://github.com/nace-ai/audit-app/issues"
+
+[project.scripts]
+ndi-mcp = "ndi_mcp._cli:main"
+
+[tool.uv.sources]
+ndi-sdk = { workspace = true }
+
+[dependency-groups]
+dev = [
+    "pyrefly>=1.0.0,<2",
+    "pytest>=8.4.0",
+    "pytest-asyncio>=1.0.0",
+    "ruff>=0.12.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 130
+fix = true
+
+[tool.ruff.lint]
+ignore = [
+    "D",
+    "ANN",
+    "PLR0913",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+addopts = ["--strict-markers", "--tb=short"]

ndi_mcp-0.1.0/src/ndi_mcp/__init__.py

@@ -0,0 +1,12 @@
+"""MCP servers for NDI: local over stdio, hosted over Streamable HTTP.
+
+Install with ``pip install ndi-mcp`` (MIT). The client library is the Apache-2.0
+``ndi-sdk`` package.
+"""
+
+from __future__ import annotations
+
+from ndi_mcp.hosted import build_hosted_server
+from ndi_mcp.server import build_server
+
+__all__ = ["build_hosted_server", "build_server"]

ndi_mcp-0.1.0/src/ndi_mcp/_cli.py

@@ -0,0 +1,39 @@
+"""``ndi-mcp`` entry point: serve over stdio, or ``login`` to store a key."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from ndi_mcp._credentials import login
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="ndi-mcp", description="NDI MCP server for coding agents.")
+    sub = parser.add_subparsers(dest="command")
+    login_p = sub.add_parser("login", help="Open a browser to authorize ndi-mcp and save the API key")
+    login_p.add_argument(
+        "--api-key",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="KEY",
+        help="Paste a key instead of opening a browser. Omit KEY to type it hidden.",
+    )
+    args = parser.parse_args(argv)
+
+    if args.command == "login":
+        prompt = args.api_key == ""
+        key = args.api_key or None
+        path = login(api_key=key, prompt=prompt)
+        print(f"saved API key to {path}", file=sys.stderr)
+        return 0
+
+    from ndi_mcp import build_server
+
+    build_server().run(transport="stdio")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ndi_mcp-0.1.0/src/ndi_mcp/_credentials.py

@@ -0,0 +1,297 @@
+"""Resolve and store the API key the MCP server forwards to NDI.
+
+Order: ``$NDI_API_KEY``, then ``~/.ndi/config.toml``. ``$NDI_BASE_URL`` wins
+over a ``base_url`` in the file. A missing key is a startup failure with the
+login hint, not a 401 on the first tool call.
+
+``ndi-mcp login`` opens a browser, polls the device-code endpoints, then writes
+the minted key after a cheap authenticated call so a typo is caught before the
+next agent session. ``$NDI_API_KEY`` and ``--api-key`` skip the browser.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+import tempfile
+import tomllib
+import webbrowser
+from collections.abc import Callable
+from dataclasses import dataclass
+from getpass import getpass
+from pathlib import Path
+from time import sleep as sleep_seconds
+
+import httpx
+
+from ndi_sdk._transport import DEFAULT_TIMEOUT
+from ndi_sdk.client import API_KEY_ENV, BASE_URL_ENV, DEFAULT_BASE_URL, NdiClient
+
+CONFIG_PATH_ENV = "NDI_CONFIG_PATH"
+DEFAULT_CONFIG_PATH = Path.home() / ".ndi" / "config.toml"
+
+Printer = Callable[[str], None]
+OpenBrowser = Callable[[str], object]
+Sleep = Callable[[float], None]
+
+
+class CredentialsError(ValueError):
+    """No API key could be resolved."""
+
+
+@dataclass(frozen=True)
+class Credentials:
+    api_key: str
+    base_url: str | None = None
+
+
+def config_path() -> Path:
+    override = os.environ.get(CONFIG_PATH_ENV)
+    return Path(override) if override else DEFAULT_CONFIG_PATH
+
+
+def resolve_credentials() -> Credentials:
+    """Use the env var, else the config file.
+
+    Raises:
+        CredentialsError: When neither source has a key.
+    """
+    api_key = os.environ.get(API_KEY_ENV)
+    base_url = os.environ.get(BASE_URL_ENV)
+    if not api_key or not base_url:
+        file_values = _read_config(config_path(), recover=bool(api_key))
+        api_key = api_key or file_values.get("api_key")
+        base_url = base_url or file_values.get("base_url")
+    if not api_key:
+        raise CredentialsError(f"no API key: set ${API_KEY_ENV} or run `ndi-mcp login`")
+    return Credentials(api_key=api_key, base_url=base_url)
+
+
+def login(
+    *,
+    api_key: str | None = None,
+    prompt: bool = False,
+    get_pass: Callable[[str], str] = getpass,
+    http_client_factory: Callable[[], httpx.Client] | None = None,
+    open_browser: OpenBrowser | None = None,
+    sleep: Sleep | None = None,
+    printer: Printer | None = None,
+) -> Path:
+    """Authorize, validate the key, and write ``~/.ndi/config.toml`` as ``0600``.
+
+    Default is a browser device-code flow. Pass ``api_key`` (or set
+    ``$NDI_API_KEY``) to skip it. ``prompt=True`` types a hidden key on a TTY.
+    """
+    existing = _read_config(config_path(), recover=True)
+    base_url = os.environ.get(BASE_URL_ENV) or existing.get("base_url")
+    _reject_control_chars(base_url, field="base_url")
+    owned = http_client_factory is None
+    http_client = http_client_factory() if http_client_factory is not None else httpx.Client(timeout=DEFAULT_TIMEOUT)
+    try:
+        key = _resolve_login_key(
+            api_key=api_key,
+            prompt=prompt,
+            get_pass=get_pass,
+            http_client=http_client,
+            base_url=base_url,
+            open_browser=open_browser,
+            sleep=sleep,
+            printer=printer,
+        )
+        with NdiClient(api_key=key, base_url=base_url, http_client=http_client) as client:
+            client.workspaces.list(limit=1)
+        return write_config(api_key=key, base_url=base_url, path=config_path())
+    finally:
+        if owned:
+            http_client.close()
+
+
+def write_config(*, api_key: str, path: Path | None = None, base_url: str | None = None) -> Path:
+    target = path or config_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    existing = _read_config(target, recover=True)
+    resolved_base = base_url if base_url is not None else existing.get("base_url")
+    _reject_control_chars(resolved_base, field="base_url")
+    lines = [f'api_key = "{_escape_toml(api_key)}"\n']
+    if resolved_base:
+        lines.append(f'base_url = "{_escape_toml(resolved_base)}"\n')
+    fd, tmp_name = tempfile.mkstemp(prefix=".ndi-config-", suffix=".toml", dir=target.parent)
+    tmp_path = Path(tmp_name)
+    try:
+        try:
+            _chmod_fd(fd)
+            _write_all(fd, "".join(lines).encode())
+        finally:
+            os.close(fd)
+        os.chmod(tmp_path, stat.S_IRUSR | stat.S_IWUSR)
+        os.replace(tmp_path, target)
+    except BaseException:
+        tmp_path.unlink(missing_ok=True)
+        raise
+    return target
+
+
+def _resolve_login_key(
+    *,
+    api_key: str | None,
+    prompt: bool,
+    get_pass: Callable[[str], str],
+    http_client: httpx.Client,
+    base_url: str | None,
+    open_browser: OpenBrowser | None,
+    sleep: Sleep | None,
+    printer: Printer | None,
+) -> str:
+    if prompt:
+        if not sys.stdin.isatty():
+            raise CredentialsError("pass --api-key KEY or run `ndi-mcp login` in a terminal")
+        api_key = get_pass("NDI API key: ")
+    if api_key is None:
+        env_key = os.environ.get(API_KEY_ENV)
+        if env_key:
+            api_key = env_key
+        else:
+            return _device_login(
+                http_client=http_client,
+                base_url=base_url,
+                open_browser=open_browser,
+                sleep=sleep,
+                printer=printer,
+            )
+    return _require_key(api_key)
+
+
+def _device_login(
+    *,
+    http_client: httpx.Client,
+    base_url: str | None,
+    open_browser: OpenBrowser | None,
+    sleep: Sleep | None,
+    printer: Printer | None,
+) -> str:
+    host = (base_url or DEFAULT_BASE_URL).rstrip("/")
+    try:
+        issued = http_client.post(f"{host}/v1/cli/device/code")
+    except httpx.HTTPError as exc:
+        raise CredentialsError("could not reach NDI; check $NDI_BASE_URL") from exc
+    payload = _json_object(issued)
+    if issued.status_code != 200:
+        raise CredentialsError("could not start login; run `ndi-mcp login` again")
+    device_code = payload.get("device_code")
+    user_code = payload.get("user_code")
+    complete = payload.get("verification_uri_complete")
+    if not isinstance(device_code, str) or not isinstance(user_code, str) or not isinstance(complete, str):
+        raise CredentialsError("could not start login; run `ndi-mcp login` again")
+    interval = _positive_int(payload.get("interval"), default=5)
+    expires_in = _positive_int(payload.get("expires_in"), default=600)
+    write = printer or (lambda line: print(line, file=sys.stderr))
+    write(f"Open {complete}")
+    write(f"Confirm this code: {user_code}")
+    opener = open_browser or webbrowser.open
+    opener(complete)
+    wait = sleep or sleep_seconds
+    elapsed = 0.0
+    poll_wait = interval
+    while elapsed < expires_in:
+        try:
+            token = http_client.post(f"{host}/v1/cli/device/token", json={"device_code": device_code})
+        except httpx.HTTPError as exc:
+            raise CredentialsError("could not reach NDI; check $NDI_BASE_URL") from exc
+        if token.status_code == 200:
+            body = _json_object(token)
+            key = body.get("api_key")
+            if not isinstance(key, str):
+                raise CredentialsError("login failed; run `ndi-mcp login` again")
+            return _require_key(key)
+        error = _device_error(token)
+        if error == "authorization_pending":
+            wait(poll_wait)
+            elapsed += poll_wait
+            continue
+        if error == "slow_down":
+            poll_wait = max(poll_wait * 2, 1)
+            wait(poll_wait)
+            elapsed += poll_wait
+            continue
+        raise CredentialsError(_device_error_message(error))
+    raise CredentialsError("login expired; run `ndi-mcp login` again")
+
+
+def _require_key(key: str) -> str:
+    if not key:
+        raise CredentialsError("API key must not be empty")
+    if any(ord(ch) < 32 or ord(ch) == 127 for ch in key):
+        raise CredentialsError("API key must not contain control characters")
+    return key
+
+
+def _json_object(response: httpx.Response) -> dict[str, object]:
+    try:
+        payload = response.json()
+    except ValueError:
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _device_error(response: httpx.Response) -> str:
+    error = _json_object(response).get("error")
+    return error if isinstance(error, str) else "expired_token"
+
+
+def _device_error_message(error: str) -> str:
+    if error == "access_denied":
+        return "login was denied; run `ndi-mcp login` again"
+    if error == "expired_token":
+        return "login expired; run `ndi-mcp login` again"
+    return "login failed; run `ndi-mcp login` again"
+
+
+def _positive_int(value: object, *, default: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        return default
+    return value
+
+
+def _chmod_fd(fd: int) -> None:
+    chmod = getattr(os, "fchmod", None)
+    if callable(chmod):
+        chmod(fd, stat.S_IRUSR | stat.S_IWUSR)
+
+
+def _write_all(fd: int, data: bytes) -> None:
+    view = memoryview(data)
+    while view:
+        written = os.write(fd, view)
+        if written == 0:
+            raise OSError("short write")
+        view = view[written:]
+
+
+def _read_config(path: Path, *, recover: bool = False) -> dict[str, str]:
+    if not path.is_file():
+        return {}
+    try:
+        with path.open("rb") as handle:
+            parsed = tomllib.load(handle)
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError):
+        if recover:
+            return {}
+        raise
+    values: dict[str, str] = {}
+    for key in ("api_key", "base_url"):
+        value = parsed.get(key)
+        if isinstance(value, str) and value:
+            values[key] = value
+    return values
+
+
+def _reject_control_chars(value: str | None, *, field: str) -> None:
+    if value is None:
+        return
+    if any(ord(ch) < 32 or ord(ch) == 127 for ch in value):
+        raise CredentialsError(f"{field} must not contain control characters")
+
+
+def _escape_toml(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')

ndi_mcp-0.1.0/src/ndi_mcp/_docs.py

@@ -0,0 +1,40 @@
+"""``get_documentation``: current SDK usage, not training memory."""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from ndi_mcp._payloads import raise_as_tool_error
+
+TOPICS = (
+    "quickstart",
+    "auth",
+    "parse",
+    "extract",
+    "split",
+    "classify",
+    "ground",
+    "upload",
+    "workspaces",
+    "jobs",
+)
+
+
+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("ndi_mcp").joinpath("docs").joinpath(f"{topic}.md").read_text()
+
+
+def register_doc_tools(mcp: FastMCP) -> None:
+    @mcp.tool()
+    async def get_documentation(topic: str) -> dict[str, Any]:
+        """Return current NDI SDK usage for a topic. Call this before writing integration code."""
+        try:
+            return {"topic": topic, "text": topic_text(topic)}
+        except ValueError as exc:
+            raise_as_tool_error(exc)
+            raise