daknode-mcp 0.1.0__py3-none-any.whl

daknode_mcp/__init__.py

@@ -0,0 +1 @@
+"""DakNode MCP server. Spec: `.agent/specs/17_agent_toolkit.md#mcp`."""

daknode_mcp/server.py

@@ -0,0 +1,229 @@
+"""DakNode MCP server — DakNode's API as tools, over stdio.
+
+Spec: `.agent/specs/17_agent_toolkit.md#mcp`.
+Boundary: `.agent/architecture.md` §0, "Where MCP, SDKs and a CLI sit".
+
+**Every tool is 1:1 with a published API operation and composes no decision.**
+That is `architecture.md` §0 consequence 4, and it is the whole boundary here.
+`create_inbox`, `list_threads`, `send` are inside the line. A tool called
+`reply_to_latest` or `auto_respond` would be outside it — DakNode would be
+choosing which message to answer, **while looking like a convenience**. That is
+how this boundary erodes: not by someone adding an agent framework, which the
+existing rule catches loudly, but by someone adding a helpful-sounding tool.
+
+If a tool cannot be named after an `operationId`, it does not belong here.
+`tests/test_mcp_server.py` enforces that rather than leaving it to review.
+
+This wraps the **generated SDK** rather than building requests itself: a second
+HTTP client would drift from the first, and the SDK is already regenerated from
+the spec and guarded against drift.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+_SDK = Path(__file__).resolve().parents[1] / "sdk" / "python"
+if str(_SDK) not in sys.path:  # pragma: no cover - import plumbing
+    sys.path.insert(0, str(_SDK))
+
+from mcp.server.mcpserver import MCPServer  # noqa: E402
+
+DEFAULT_BASE_URL = "https://api.daknode.com"
+
+
+def _version() -> str:
+    """The installed `daknode-mcp` version, so a client can report what it runs.
+
+    Read from package metadata rather than written here a second time; a copy
+    run from the repository, not installed, reports itself as such.
+    """
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("daknode-mcp")
+    except PackageNotFoundError:
+        return "0.0.0+checkout"
+
+
+class MissingApiKey(RuntimeError):
+    """No credential. Raised at STARTUP, not at first tool call.
+
+    A server that starts happily and then fails every call looks like a broken
+    tool rather than a missing setting, and the person debugging it is an agent.
+    """
+
+
+def _client():
+    """Build the SDK client from the environment.
+
+    The key comes from `DAKNODE_API_KEY` and **never from argv**: command-line
+    arguments are visible to every process on the machine through `ps`, and
+    shells record them in history.
+    """
+    key = os.environ.get("DAKNODE_API_KEY", "").strip()
+    if not key:
+        raise MissingApiKey(
+            "DAKNODE_API_KEY is not set. Put it in the MCP client's environment "
+            "configuration for this server."
+        )
+    from daknode import AuthenticatedClient
+
+    return AuthenticatedClient(
+        base_url=os.environ.get("DAKNODE_BASE_URL", DEFAULT_BASE_URL).rstrip("/"),
+        token=key,
+    )
+
+
+def _result(response) -> Any:
+    """Return the parsed body, or a readable failure.
+
+    Never raises to the agent: an MCP tool that throws gives the model a stack
+    trace, which it cannot act on and may repeat back to a user.
+    """
+    parsed = getattr(response, "parsed", None)
+    if parsed is not None:
+        return parsed.to_dict() if hasattr(parsed, "to_dict") else parsed
+    return {
+        "status": getattr(response, "status_code", None),
+        "error": (getattr(response, "content", b"") or b"").decode("utf-8", "replace")[:500],
+    }
+
+
+def build_server() -> MCPServer:
+    """Register one tool per published operation.
+
+    **Deliberately NOT exposed:** erasure. It is irreversible, and an agent that
+    can erase a data subject through a tool call is a liability no convenience
+    justifies (spec §5). It stays an explicit API call a human integrates.
+    Console, operator and provider-callback surfaces are absent for the same
+    reason the SDK omits them.
+    """
+    server = MCPServer(
+        name="daknode",
+        title="DakNode",
+        version=_version(),
+        website_url="https://daknode.com",
+        description=(
+            "Email for software agents: provision an inbox, read threads, "
+            "search, and send."
+        ),
+    )
+
+    @server.tool()
+    def create_inbox() -> Any:
+        """Create a new agent inbox and return its id and address.
+
+        The same address both sends and receives. Inbound mail arrives by
+        webhook; use `list_threads` and `get_thread` to read history.
+        """
+        from daknode.api.inboxes import create_inbox as op
+        from daknode.models import InboxCreateRequest
+
+        with _client() as c:
+            return _result(op.sync_detailed(client=c, body=InboxCreateRequest()))
+
+    @server.tool()
+    def list_threads(inbox_id: str, limit: int = 25, cursor: str | None = None) -> Any:
+        """List conversations in an inbox, most recently active first."""
+        from daknode.api.messages import list_threads as op
+        from daknode.types import UNSET
+
+        with _client() as c:
+            return _result(op.sync_detailed(
+                inbox_id=inbox_id, client=c, limit=limit,
+                cursor=cursor if cursor else UNSET,
+            ))
+
+    @server.tool()
+    def list_messages(inbox_id: str, limit: int = 25, cursor: str | None = None) -> Any:
+        """List messages in an inbox, newest first."""
+        from daknode.api.messages import list_messages as op
+        from daknode.types import UNSET
+
+        with _client() as c:
+            return _result(op.sync_detailed(
+                inbox_id=inbox_id, client=c, limit=limit,
+                cursor=cursor if cursor else UNSET,
+            ))
+
+    @server.tool()
+    def get_thread(thread_id: str) -> Any:
+        """Fetch one conversation with both sides, oldest first."""
+        from daknode.api.messages import get_thread as op
+
+        with _client() as c:
+            return _result(op.sync_detailed(thread_id=thread_id, client=c))
+
+    @server.tool()
+    def get_message(message_id: str) -> Any:
+        """Fetch one message by id.
+
+        `body_text` is already cleaned: quoted history and signatures are
+        stripped, so there is no reply chain to parse out of it. Check
+        `risk_level` before feeding the content to a model — `high` means
+        prompt-injection patterns were detected in mail from the internet.
+        """
+        from daknode.api.messages import get_message as op
+
+        with _client() as c:
+            return _result(op.sync_detailed(message_id=message_id, client=c))
+
+    @server.tool()
+    def search(query: str, top_k: int = 10) -> Any:
+        """Semantic search over this caller's own mail.
+
+        Returns identifiers and scores, not content — resolve them with
+        `get_message` or `get_thread`.
+        """
+        from daknode.api.search import search as op
+        from daknode.models import SearchRequest
+
+        with _client() as c:
+            return _result(op.sync_detailed(
+                client=c, body=SearchRequest(query=query, top_k=top_k)
+            ))
+
+    @server.tool()
+    def send(
+        inbox_id: str,
+        to: str,
+        subject: str,
+        body_text: str,
+        thread_id: str | None = None,
+    ) -> Any:
+        """Send a message.
+
+        Pass `thread_id` to reply into a conversation: the server derives
+        `In-Reply-To` and `References` from that thread's latest received
+        message. Without it the message opens a NEW conversation in the
+        recipient's client — it does not continue one.
+        """
+        from daknode.api.send import send as op
+        from daknode.models import SendRequest
+        from daknode.types import UNSET
+
+        with _client() as c:
+            return _result(op.sync_detailed(client=c, body=SendRequest(
+                inbox_id=inbox_id, to=to, subject=subject, body_text=body_text,
+                thread_id=thread_id if thread_id else UNSET,
+            )))
+
+    return server
+
+
+def main() -> int:  # pragma: no cover - process entry point
+    try:
+        _client()
+    except MissingApiKey as exc:
+        print(f"daknode-mcp: {exc}", file=sys.stderr)
+        return 2
+    build_server().run()
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

daknode_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: daknode-mcp
+Version: 0.1.0
+Summary: DakNode's email API as MCP tools for AI agents, over stdio.
+Project-URL: Homepage, https://daknode.com
+Project-URL: Documentation, https://daknode.com/developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: daknode<0.2,>=0.1
+Requires-Dist: mcp<3,>=2.2
+
+# DakNode MCP server
+
+DakNode's API as MCP tools, over **stdio**. The client launches it as a
+subprocess; there is no hosted endpoint and no infrastructure.
+
+## Install
+
+Python 3.10+. With [uv](https://docs.astral.sh/uv/), nothing needs installing
+up front — the client starts it with `uvx`. Otherwise `pipx install daknode-mcp`.
+
+Get an API key with the two-request signup at <https://daknode.com/developers>.
+
+## Configure
+
+```json
+{
+  "mcpServers": {
+    "daknode": {
+      "command": "uvx",
+      "args": ["daknode-mcp"],
+      "env": { "DAKNODE_API_KEY": "…" }
+    }
+  }
+}
+```
+
+With `pipx`, use `"command": "daknode-mcp"` and no `args`. From a repository
+checkout, `"command": "python", "args": ["-m", "mcp_server.server"]`.
+
+The key comes from the environment and **never from a command-line argument**:
+argv is visible to every process through `ps`, and shells record it in history.
+The server refuses to start without it, so a misconfiguration is obvious at
+launch rather than looking like a broken tool.
+
+## Tools
+
+`create_inbox` · `list_threads` · `list_messages` · `get_thread` · `get_message`
+· `search` · `send`
+
+**Every tool is 1:1 with a published API operation.** That is `architecture.md`
+§0 consequence 4, and it is the boundary this server exists inside: DakNode
+exposes operations, the agent decides which to call. A tool like
+`reply_to_latest` or `auto_respond` would cross that line — DakNode would be
+choosing which message to answer — **while looking like a convenience**.
+`tests/test_mcp_server.py` enforces it rather than leaving it to review.
+
+## What is deliberately absent
+
+**Erasure.** It is irreversible, and an agent that can erase a data subject
+through a tool call is a liability no convenience justifies. It stays an
+explicit API call a human integrates.
+
+**Console and operator APIs.** Not a product surface.
+
+## Notes for whoever uses this
+
+`send` without `thread_id` opens a **new** conversation in the recipient's
+client. Pass `thread_id` to reply into an existing one — the server then derives
+`In-Reply-To` and `References` from that thread's latest received message.
+
+`search` returns identifiers and scores, **not content**. Resolve them with
+`get_message` or `get_thread`.
+
+`body_text` is already cleaned: quoted history and signatures are stripped.
+Check `risk_level` before feeding content to a model — `high` means
+prompt-injection patterns were detected in mail from the internet.

daknode_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+daknode_mcp/__init__.py,sha256=aStm9Q8imB2PI4r10dRlsqnGqzFk9RxVQrGBK-rAcmo,72
+daknode_mcp/server.py,sha256=gph8wVTzdZrLvpIK9VG_eaHbfKlkcJWyFRNpAZTUUV0,8188
+daknode_mcp-0.1.0.dist-info/METADATA,sha256=LjNHwKEUp8EByuqNHia0fQR50e45VGM_3K_sDntj3ss,2799
+daknode_mcp-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+daknode_mcp-0.1.0.dist-info/entry_points.txt,sha256=M48Ha35idxlU9DveXX4tXQFNGIDeNtcJAPiNg5ZP4tk,56
+daknode_mcp-0.1.0.dist-info/top_level.txt,sha256=-Ag_P5pqnxaZXjvkbfQ16tTYG4ch4oSTpHG78xkXFCA,12
+daknode_mcp-0.1.0.dist-info/RECORD,,

daknode_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

daknode_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+daknode-mcp = daknode_mcp.server:main

daknode_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+daknode_mcp