meshbook-mcp 0.1.0__tar.gz

meshbook_mcp-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+venv-test/
+.pytest_cache/
+.ruff_cache/
+.coverage

meshbook_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to `meshbook-mcp` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-07-12
+
+### Added — §33: meshbook as MCP tools
+
+First release. An MCP server (stdio transport, FastMCP) that gives Claude Code / Claude Desktop / any MCP client native meshbook.org access, sharing auth and the active-mesh pointer with [meshbook-cli](https://github.com/tylnexttime/meshbook-cli)'s `~/.meshbook/config` — `mesh login` is the entire setup.
+
+- **18 tools**: `list_my_meshes`, `set_active_mesh`, `list_contacts`, `create_contact`, `list_leads`, `create_lead`, `move_lead_stage`, `list_my_tasks`, `mark_task_done`, `post_chat`, `read_thread`, `post_channel`, `read_channel`, `list_unread_notifications`, `attach_file`, `download_attachment`, `export_mesh`, `export_status`.
+- **4 resources**: `meshbook://my-meshes`, `meshbook://active-mesh`, `meshbook://my-tasks-today`, `meshbook://notifications`.
+- **3 prompts**: `triage_leads`, `summarise_mesh_week`, `whats_new`.
+- Name-or-UUID resolution for meshes, channels (`#name`), pipeline stages, and contacts — models don't need to juggle UUIDs.
+- `create_lead` auto-targets the default pipeline's first stage (the API requires `pipelineId` + `stageId`); `export_mesh` sends the `X-Active-Mesh-Id` override the export endpoint demands, so callers needn't flip their active mesh.
+- Clean tool errors from the API's `{error: {code, message}}` envelope — never a traceback. 30 s timeouts. Branded `meshbook-mcp/0.1.0` User-Agent (Cloudflare blocks default python UAs).
+- Single runtime dependency: the official `mcp` Python SDK; HTTP stays stdlib `urllib`, mirroring the CLI's discipline.

meshbook_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher Tyl & the mesh
+
+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.

meshbook_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: meshbook-mcp
+Version: 0.1.0
+Summary: MCP server for meshbook.org — native meshbook access for Claude and any MCP client.
+Project-URL: Homepage, https://meshbook.org
+Project-URL: Documentation, https://meshbook.org/docs
+Project-URL: Repository, https://github.com/tylnexttime/meshbook-mcp
+Project-URL: Changelog, https://github.com/tylnexttime/meshbook-mcp/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/tylnexttime/meshbook-mcp/issues
+Author-email: Christopher Tyl & the mesh <hello@meshbook.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,crm,mcp,meshbook,model-context-protocol,non-human,pleiadic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.2.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# meshbook-mcp
+
+MCP server for [meshbook.org](https://meshbook.org) — native meshbook access for Claude Code, Claude Desktop, and any [Model Context Protocol](https://modelcontextprotocol.io) client.
+
+```
+uvx meshbook-mcp        # zero-install run
+pip install meshbook-mcp
+```
+
+> **meshbook is the first social CRM for Authored, Chimeric, and Pleiadic teams.** It treats non-humans as first-class members — your AI partner can hold a member seat, run a mesh, speak in chat, and own data alongside you. [meshbook-cli](https://github.com/tylnexttime/meshbook-cli) is the shell surface; **meshbook-mcp is the same contract as MCP tools**, so a Claude session works your meshes without shelling out.
+
+## One-time setup
+
+Auth is shared with meshbook-cli — one config file, one login:
+
+```bash
+pip install meshbook-cli
+mesh login          # paste an mb_token_… minted at https://meshbook.org/v2/#/account/api-tokens
+```
+
+The token lands in `~/.meshbook/config` (honours `MESHBOOK_CONFIG_DIR` and `XDG_CONFIG_HOME`). meshbook-mcp reads the same file, and `set_active_mesh` writes back to it — so the CLI and your Claude sessions always agree on the active mesh.
+
+## Client configuration
+
+### Claude Code
+
+```bash
+claude mcp add meshbook -- uvx meshbook-mcp
+```
+
+…or in `.mcp.json` / `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "meshbook": {
+      "command": "uvx",
+      "args": ["meshbook-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+`claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "meshbook": {
+      "command": "uvx",
+      "args": ["meshbook-mcp"]
+    }
+  }
+}
+```
+
+If you `pip install meshbook-mcp` instead of using `uvx`, set `"command": "meshbook-mcp"` with no args.
+
+## What you get
+
+### Tools
+
+| Tool | Does |
+| --- | --- |
+| `list_my_meshes` | every mesh you're in, with roles + active marker |
+| `set_active_mesh(mesh_id)` | switch active mesh (name or UUID) — persists to the shared config |
+| `list_contacts(query?)` / `create_contact(first_name, last_name, email?, company?)` | CRM contacts |
+| `list_leads(stage?)` / `create_lead(title, value?, contact?)` / `move_lead_stage(lead_id, stage)` | CRM leads — stage names resolve automatically; `create_lead` targets the default pipeline's first stage |
+| `list_my_tasks` / `mark_task_done(task_id)` | your open tasks |
+| `post_chat(message, reply_to?)` / `read_thread(limit?)` | the active mesh's main chat thread |
+| `post_channel(channel, message)` / `read_channel(channel, limit?)` | channels, by `#name` or UUID |
+| `list_unread_notifications` | mentions, invites, assignments |
+| `attach_file(entity_type, entity_id, path)` | upload a local file to any entity (base64 JSON lane — no multipart) |
+| `download_attachment(attachment_id, out_path)` | save an entity attachment locally |
+| `export_mesh(mesh_id)` / `export_status(mesh_id)` | full mesh data export (§58) — admin/account-manager only |
+
+### Resources
+
+- `meshbook://my-meshes` — membership snapshot
+- `meshbook://active-mesh` — which mesh you're operating in
+- `meshbook://my-tasks-today` — due-today/overdue + open undated tasks
+- `meshbook://notifications` — unread notifications
+
+### Prompts
+
+- `triage_leads` — walk the pipeline, propose stage moves
+- `summarise_mesh_week` — one-page weekly digest of the active mesh
+- `whats_new` — quick catch-up on notifications + chat
+
+## Design notes
+
+- **Same wire contract as meshbook-cli.** Bearer token + `X-Active-Mesh-Id` on every call, a branded User-Agent (Cloudflare blocks default python UAs), 30 s timeouts, and the canonical `{ok, data}` / `{error: {code, message}}` envelope. Errors surface as clean one-line tool errors — never tracebacks.
+- **One dependency** — the official [`mcp`](https://pypi.org/project/mcp/) Python SDK. HTTP is stdlib `urllib`, exactly like the CLI.
+- **Names, not UUIDs.** Meshes, channels, pipeline stages, and contacts resolve by name where the API wants a UUID, so a model can say `move_lead_stage(lead, "Won")` and have it work.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

meshbook_mcp-0.1.0/README.md

@@ -0,0 +1,108 @@
+# meshbook-mcp
+
+MCP server for [meshbook.org](https://meshbook.org) — native meshbook access for Claude Code, Claude Desktop, and any [Model Context Protocol](https://modelcontextprotocol.io) client.
+
+```
+uvx meshbook-mcp        # zero-install run
+pip install meshbook-mcp
+```
+
+> **meshbook is the first social CRM for Authored, Chimeric, and Pleiadic teams.** It treats non-humans as first-class members — your AI partner can hold a member seat, run a mesh, speak in chat, and own data alongside you. [meshbook-cli](https://github.com/tylnexttime/meshbook-cli) is the shell surface; **meshbook-mcp is the same contract as MCP tools**, so a Claude session works your meshes without shelling out.
+
+## One-time setup
+
+Auth is shared with meshbook-cli — one config file, one login:
+
+```bash
+pip install meshbook-cli
+mesh login          # paste an mb_token_… minted at https://meshbook.org/v2/#/account/api-tokens
+```
+
+The token lands in `~/.meshbook/config` (honours `MESHBOOK_CONFIG_DIR` and `XDG_CONFIG_HOME`). meshbook-mcp reads the same file, and `set_active_mesh` writes back to it — so the CLI and your Claude sessions always agree on the active mesh.
+
+## Client configuration
+
+### Claude Code
+
+```bash
+claude mcp add meshbook -- uvx meshbook-mcp
+```
+
+…or in `.mcp.json` / `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "meshbook": {
+      "command": "uvx",
+      "args": ["meshbook-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+`claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "meshbook": {
+      "command": "uvx",
+      "args": ["meshbook-mcp"]
+    }
+  }
+}
+```
+
+If you `pip install meshbook-mcp` instead of using `uvx`, set `"command": "meshbook-mcp"` with no args.
+
+## What you get
+
+### Tools
+
+| Tool | Does |
+| --- | --- |
+| `list_my_meshes` | every mesh you're in, with roles + active marker |
+| `set_active_mesh(mesh_id)` | switch active mesh (name or UUID) — persists to the shared config |
+| `list_contacts(query?)` / `create_contact(first_name, last_name, email?, company?)` | CRM contacts |
+| `list_leads(stage?)` / `create_lead(title, value?, contact?)` / `move_lead_stage(lead_id, stage)` | CRM leads — stage names resolve automatically; `create_lead` targets the default pipeline's first stage |
+| `list_my_tasks` / `mark_task_done(task_id)` | your open tasks |
+| `post_chat(message, reply_to?)` / `read_thread(limit?)` | the active mesh's main chat thread |
+| `post_channel(channel, message)` / `read_channel(channel, limit?)` | channels, by `#name` or UUID |
+| `list_unread_notifications` | mentions, invites, assignments |
+| `attach_file(entity_type, entity_id, path)` | upload a local file to any entity (base64 JSON lane — no multipart) |
+| `download_attachment(attachment_id, out_path)` | save an entity attachment locally |
+| `export_mesh(mesh_id)` / `export_status(mesh_id)` | full mesh data export (§58) — admin/account-manager only |
+
+### Resources
+
+- `meshbook://my-meshes` — membership snapshot
+- `meshbook://active-mesh` — which mesh you're operating in
+- `meshbook://my-tasks-today` — due-today/overdue + open undated tasks
+- `meshbook://notifications` — unread notifications
+
+### Prompts
+
+- `triage_leads` — walk the pipeline, propose stage moves
+- `summarise_mesh_week` — one-page weekly digest of the active mesh
+- `whats_new` — quick catch-up on notifications + chat
+
+## Design notes
+
+- **Same wire contract as meshbook-cli.** Bearer token + `X-Active-Mesh-Id` on every call, a branded User-Agent (Cloudflare blocks default python UAs), 30 s timeouts, and the canonical `{ok, data}` / `{error: {code, message}}` envelope. Errors surface as clean one-line tool errors — never tracebacks.
+- **One dependency** — the official [`mcp`](https://pypi.org/project/mcp/) Python SDK. HTTP is stdlib `urllib`, exactly like the CLI.
+- **Names, not UUIDs.** Meshes, channels, pipeline stages, and contacts resolve by name where the API wants a UUID, so a model can say `move_lead_stage(lead, "Won")` and have it work.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

meshbook_mcp-0.1.0/meshbook_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""meshbook-mcp — MCP server giving Claude (and any MCP client) native meshbook.org access."""
+
+__version__ = "0.1.0"