dlb-mcp 0.1.0__tar.gz

dlb_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Create venv and sync deps
+        run: |
+          uv venv -p ${{ matrix.python-version }}
+          uv sync
+
+      - name: Lint with ruff
+        run: uv run ruff check .
+
+      - name: Format check with ruff
+        run: uv run ruff format --check .
+
+      - name: Run tests
+        run: uv run pytest -v

dlb_mcp-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# uv
+.venv/
+# uv.lock IS committed — gives reproducible CI + dev environments.
+# It only affects local installs / CI, not what consumers get via pip install.
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# DLB local store (for any accidental runs in repo dir)
+store.sqlite3
+store.sqlite3-wal
+store.sqlite3-shm

dlb_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordan S Pilgrim
+
+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.

dlb_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: dlb-mcp
+Version: 0.1.0
+Summary: Dead Letter Box: a tiny MCP server for independent agent sessions to leave each other notes. Six tools, no daemon, real dead-letter semantics.
+Project-URL: Homepage, https://github.com/jordanspilgrim/dlb-mcp
+Project-URL: Repository, https://github.com/jordanspilgrim/dlb-mcp
+Project-URL: Issues, https://github.com/jordanspilgrim/dlb-mcp/issues
+Author: Jordan S Pilgrim
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.2.0
+Description-Content-Type: text/markdown
+
+# DLB — Dead Letter Box
+
+A tiny MCP server that lets independent AI-agent sessions leave each other notes. Fire-and-forget. Queued for non-existent recipients. No daemon. Six tools.
+
+## Why
+
+If you've ever had two Claude Code / Cursor / Codex sessions running in different terminals and wished they could coordinate, you've hit the gap DLB fills. Existing options (mcp_agent_mail, agent frameworks like CrewAI/AutoGen) either bundle too much (40+ tools, contact policies, file leases) or only work inside a single parent process.
+
+DLB does one thing: messages between agent sessions. It does NOT do orchestration, contact handshakes, file reservations, push notifications, web hosting, or auto-name-generation. If you want those, you want a different tool.
+
+## Five differentiators (vs. mcp_agent_mail and friends)
+
+1. **6 tools** — fits cleanly in Claude Code's tool list without crowding out the builtins.
+2. **No daemon** — each MCP call opens SQLite, runs one transaction, closes. No `server.lock`, no port management.
+3. **Names accepted as-is** — call yourself `alpha`, `ThreadBeta`, `worker-1`. DLB will not rename you.
+4. **Real dead-letter semantics** — `send(to="ghost")` succeeds and queues the message; if/when someone registers as `ghost`, the messages are waiting.
+5. **Zero ceremony** — `send` works on call one. Registration is optional and observational.
+
+## Install
+
+```bash
+uv tool install dlb-mcp
+```
+
+Or zero-install:
+
+```bash
+uvx dlb-mcp
+```
+
+## Wire into Claude Code
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "dlb": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["dlb-mcp"]
+    }
+  }
+}
+```
+
+Multiple sessions can coexist — they all share `~/.dlb/store.sqlite3` via SQLite WAL mode.
+
+## The 6 tools
+
+| Tool | What it does |
+|---|---|
+| `register(name, working_on=None, force=False)` | Declare a name + status. Returns `session_token`. Conflict on existing active name → error with suggestion. |
+| `list_threads(active_within="24h")` | See who's around. No auth. |
+| `send(to, body, subject=None, from_=None)` | Drop a message. Always succeeds — even if `to` doesn't exist yet. |
+| `read(name, session_token, unread_only=True, limit=20)` | Read inbox. Requires session_token for registered names. |
+| `ack(message_id, session_token)` | Explicit "I saw this and acted on it". Optional. |
+| `unregister(name, session_token)` | Release the name. Messages preserved for re-registration. |
+
+That's the entire API.
+
+## Configuration
+
+| Env var | Default | What |
+|---|---|---|
+| `DLB_STORE` | `~/.dlb/store.sqlite3` | Path to the SQLite store |
+| `DLB_MESSAGE_TTL_DAYS` | `7` | Days before unread messages expire |
+
+## Security model
+
+- **Local-only.** File permissions (`~/.dlb/` is `chmod 700`) are the boundary.
+- **Send is open.** Anyone can drop messages in any inbox. By design — DLB is a relay.
+- **Read is gated.** Once a name is registered, only the holder of that session's token can read it.
+- **No TLS, no accounts, no cross-host.** If you need those, you want a different tool.
+
+## What DLB is NOT
+
+- Not an orchestrator. Use a script + your LLM SDK if you need to spawn agents.
+- Not a web service. Local only.
+- Not Gmail. No threading, replies, CC/BCC, attachments, contacts, importance flags.
+- Not a file-coordination tool. No file leases or advisory locks.
+- Not push. Polling-only — call `read` when you want to check.
+
+If you find yourself wishing for any of these, that's a signal to use a different tool, not to ask DLB to grow.
+
+## License
+
+MIT.

dlb_mcp-0.1.0/README.md

@@ -0,0 +1,88 @@
+# DLB — Dead Letter Box
+
+A tiny MCP server that lets independent AI-agent sessions leave each other notes. Fire-and-forget. Queued for non-existent recipients. No daemon. Six tools.
+
+## Why
+
+If you've ever had two Claude Code / Cursor / Codex sessions running in different terminals and wished they could coordinate, you've hit the gap DLB fills. Existing options (mcp_agent_mail, agent frameworks like CrewAI/AutoGen) either bundle too much (40+ tools, contact policies, file leases) or only work inside a single parent process.
+
+DLB does one thing: messages between agent sessions. It does NOT do orchestration, contact handshakes, file reservations, push notifications, web hosting, or auto-name-generation. If you want those, you want a different tool.
+
+## Five differentiators (vs. mcp_agent_mail and friends)
+
+1. **6 tools** — fits cleanly in Claude Code's tool list without crowding out the builtins.
+2. **No daemon** — each MCP call opens SQLite, runs one transaction, closes. No `server.lock`, no port management.
+3. **Names accepted as-is** — call yourself `alpha`, `ThreadBeta`, `worker-1`. DLB will not rename you.
+4. **Real dead-letter semantics** — `send(to="ghost")` succeeds and queues the message; if/when someone registers as `ghost`, the messages are waiting.
+5. **Zero ceremony** — `send` works on call one. Registration is optional and observational.
+
+## Install
+
+```bash
+uv tool install dlb-mcp
+```
+
+Or zero-install:
+
+```bash
+uvx dlb-mcp
+```
+
+## Wire into Claude Code
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "dlb": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["dlb-mcp"]
+    }
+  }
+}
+```
+
+Multiple sessions can coexist — they all share `~/.dlb/store.sqlite3` via SQLite WAL mode.
+
+## The 6 tools
+
+| Tool | What it does |
+|---|---|
+| `register(name, working_on=None, force=False)` | Declare a name + status. Returns `session_token`. Conflict on existing active name → error with suggestion. |
+| `list_threads(active_within="24h")` | See who's around. No auth. |
+| `send(to, body, subject=None, from_=None)` | Drop a message. Always succeeds — even if `to` doesn't exist yet. |
+| `read(name, session_token, unread_only=True, limit=20)` | Read inbox. Requires session_token for registered names. |
+| `ack(message_id, session_token)` | Explicit "I saw this and acted on it". Optional. |
+| `unregister(name, session_token)` | Release the name. Messages preserved for re-registration. |
+
+That's the entire API.
+
+## Configuration
+
+| Env var | Default | What |
+|---|---|---|
+| `DLB_STORE` | `~/.dlb/store.sqlite3` | Path to the SQLite store |
+| `DLB_MESSAGE_TTL_DAYS` | `7` | Days before unread messages expire |
+
+## Security model
+
+- **Local-only.** File permissions (`~/.dlb/` is `chmod 700`) are the boundary.
+- **Send is open.** Anyone can drop messages in any inbox. By design — DLB is a relay.
+- **Read is gated.** Once a name is registered, only the holder of that session's token can read it.
+- **No TLS, no accounts, no cross-host.** If you need those, you want a different tool.
+
+## What DLB is NOT
+
+- Not an orchestrator. Use a script + your LLM SDK if you need to spawn agents.
+- Not a web service. Local only.
+- Not Gmail. No threading, replies, CC/BCC, attachments, contacts, importance flags.
+- Not a file-coordination tool. No file leases or advisory locks.
+- Not push. Polling-only — call `read` when you want to check.
+
+If you find yourself wishing for any of these, that's a signal to use a different tool, not to ask DLB to grow.
+
+## License
+
+MIT.

dlb_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "dlb-mcp"
+version = "0.1.0"
+description = "Dead Letter Box: a tiny MCP server for independent agent sessions to leave each other notes. Six tools, no daemon, real dead-letter semantics."
+readme = "README.md"
+authors = [{ name = "Jordan S Pilgrim" }]
+license = { text = "MIT" }
+requires-python = ">=3.11"
+dependencies = [
+    "mcp[cli]>=1.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jordanspilgrim/dlb-mcp"
+Repository = "https://github.com/jordanspilgrim/dlb-mcp"
+Issues = "https://github.com/jordanspilgrim/dlb-mcp/issues"
+
+[project.scripts]
+dlb-mcp = "dlb_mcp.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dlb_mcp"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.7",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

dlb_mcp-0.1.0/src/dlb_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""Dead Letter Box — a tiny MCP server for inter-agent messaging.
+
+Six tools, no daemon, real dead-letter semantics. See README.md.
+"""
+
+__version__ = "0.1.0"

dlb_mcp-0.1.0/src/dlb_mcp/__main__.py

@@ -0,0 +1,34 @@
+"""Entry point: ``dlb-mcp`` or ``python -m dlb_mcp``.
+
+Single subcommand for v1: run the stdio MCP server. We don't bother with a
+real CLI parser — there's nothing else to do.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .server import serve_stdio
+
+
+def main() -> None:
+    # Accept --help / -h politely so users probing the binary aren't confused
+    if len(sys.argv) > 1 and sys.argv[1] in ("--help", "-h"):
+        sys.stdout.write(
+            "dlb-mcp — Dead Letter Box MCP server (stdio transport).\n"
+            "\n"
+            "Usage: dlb-mcp\n"
+            "\n"
+            "Run this command as your MCP server entry; it speaks the MCP\n"
+            "protocol over stdin/stdout. Not interactive.\n"
+            "\n"
+            "Env vars:\n"
+            "  DLB_STORE              Path to SQLite store (default ~/.dlb/store.sqlite3)\n"
+            "  DLB_MESSAGE_TTL_DAYS   Days before unread messages expire (default 7)\n"
+        )
+        return
+    serve_stdio()
+
+
+if __name__ == "__main__":
+    main()

dlb_mcp-0.1.0/src/dlb_mcp/server.py

@@ -0,0 +1,200 @@
+"""FastMCP server exposing DLB's six tools over stdio.
+
+This module is a thin façade — all real logic lives in store.py. The tools
+here exist only to:
+    1. Receive MCP arguments and dispatch to store functions
+    2. Convert store dataclasses to plain dicts for JSON-RPC serialization
+    3. Translate store exceptions into MCP-friendly error responses
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from . import store
+
+mcp = FastMCP(
+    name="dlb",
+    instructions=(
+        "DLB — Dead Letter Box. Six tools for inter-agent messaging:\n"
+        "  register, list_threads, send, read, ack, unregister.\n"
+        "Send is open (no auth). Read/ack/unregister on a registered name "
+        "require its session_token.\n"
+        "Sends to nonexistent recipients are queued and delivered on later registration."
+    ),
+)
+
+
+# ── Serialization helpers ────────────────────────────────────────────────────
+
+
+def _agent_summary_dict(s: store.AgentSummary) -> dict[str, Any]:
+    return {
+        "name": s.name,
+        "working_on": s.working_on,
+        "last_seen": s.last_seen.isoformat(),
+        "unread_count": s.unread_count,
+        "stale": s.stale,
+    }
+
+
+def _message_dict(m: store.Message) -> dict[str, Any]:
+    return {
+        "id": m.id,
+        "recipient_name": m.recipient_name,
+        "sender_name": m.sender_name,
+        "subject": m.subject,
+        "body": m.body,
+        "sent_at": m.sent_at.isoformat(),
+        "read_at": m.read_at.isoformat() if m.read_at else None,
+        "expires_at": m.expires_at.isoformat(),
+    }
+
+
+# ── Tools ────────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def register(
+    name: str,
+    working_on: str | None = None,
+    force: bool = False,
+) -> dict[str, Any]:
+    """Declare or refresh an agent identity.
+
+    Returns the agent record plus a `session_token` you must keep — it's
+    required for `read`, `ack`, and `unregister` on this name.
+
+    Conflict behavior: if the name is already registered to an active
+    session and you don't pass `force=True`, raises an error with up to
+    three suggested alternatives (e.g., `alpha-2`, `alpha-3`).
+
+    Args:
+        name: Stable identifier you'll be addressed by. Accepted as-given
+            (no rename, no auto-suffix). Examples: "alpha", "ThreadBeta",
+            "worker-1".
+        working_on: Free-text description of what this agent is doing.
+            Shown to other agents via `list_threads`. Optional.
+        force: If True, evict the prior session holding this name and
+            take it over. Use with care — silently kicks the previous owner.
+    """
+    return store.register(name, working_on=working_on, force=force)
+
+
+@mcp.tool()
+def list_threads(active_within_hours: int = 24) -> list[dict[str, Any]]:
+    """List all known agents with their unread counts and staleness flags.
+
+    No auth required. Use this to discover who's around before sending.
+    Agents whose `last_seen` is older than `active_within_hours` are marked
+    `stale=True` but still returned (so you can see "alpha was here last week").
+
+    Args:
+        active_within_hours: How many hours back to consider 'active' for
+            the staleness flag. Default 24.
+    """
+    items = store.list_threads(active_within=timedelta(hours=active_within_hours))
+    return [_agent_summary_dict(s) for s in items]
+
+
+@mcp.tool()
+def send(
+    to: str,
+    body: str,
+    subject: str | None = None,
+    from_: str | None = None,
+) -> dict[str, Any]:
+    """Drop a message into `to`'s inbox.
+
+    ALWAYS succeeds, even if `to` is not registered yet. This is DLB's
+    namesake feature — messages queue under the name, and will be in the
+    recipient's inbox when they register (or whenever someone reads under
+    that name).
+
+    No auth required. The sender is identified by the `from_` field you
+    pass; if omitted, it's the literal string "anonymous". DLB does not
+    try to auto-identify the caller.
+
+    Args:
+        to: Recipient name.
+        body: Message body (free text / Markdown).
+        subject: Optional short subject line.
+        from_: Sender label. Defaults to "anonymous".
+    """
+    msg = store.send(to=to, body=body, subject=subject, from_=from_)
+    return _message_dict(msg)
+
+
+@mcp.tool()
+def read(
+    name: str,
+    session_token: str | None = None,
+    unread_only: bool = True,
+    limit: int = 20,
+) -> list[dict[str, Any]]:
+    """Read messages in `name`'s inbox. Auto-marks them read.
+
+    Auth rules:
+    - If `name` is registered, `session_token` must match.
+    - If `name` is NOT registered, anyone can read (no owner to protect).
+      You can use this to peek at the dead-letter queue before claiming
+      a name.
+
+    Args:
+        name: The inbox to read.
+        session_token: Required if `name` is registered; ignored otherwise.
+        unread_only: If True (default), only returns messages with read_at
+            still NULL at the time of this call.
+        limit: Max messages to return (1-1000). Default 20.
+    """
+    msgs = store.read(
+        name=name,
+        session_token=session_token,
+        unread_only=unread_only,
+        limit=limit,
+    )
+    return [_message_dict(m) for m in msgs]
+
+
+@mcp.tool()
+def ack(message_id: int, session_token: str) -> dict[str, Any]:
+    """Explicitly acknowledge a message ("I saw this and acted on it").
+
+    Optional — `read` already marks messages as read. Use ack to record a
+    stronger signal. v1 treats ack as "definitely read" (sets read_at if
+    not already set). The read/ack distinction is reserved for future use.
+
+    Args:
+        message_id: The message ID from `send` or `read`.
+        session_token: Token for the message's recipient. Required.
+    """
+    ok = store.ack(message_id, session_token)
+    return {"ok": ok, "message_id": message_id}
+
+
+@mcp.tool()
+def unregister(name: str, session_token: str) -> dict[str, Any]:
+    """Release a name. Messages addressed to it are PRESERVED.
+
+    Re-registering the same name (by anyone) restores access to the
+    waiting messages. Use this when an agent session is exiting and
+    won't be back, OR when you want to hand the name to someone else
+    cleanly (instead of letting them `force` it).
+
+    Args:
+        name: The name to release.
+        session_token: Must match the current holder.
+    """
+    ok = store.unregister(name, session_token)
+    return {"ok": ok, "name": name}
+
+
+# ── Stdio entry point ────────────────────────────────────────────────────────
+
+
+def serve_stdio() -> None:
+    """Run the MCP server over stdio. Used by Claude Code / Cursor / Codex."""
+    mcp.run("stdio")