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