generated from coulomb/repo-seed
tegwick
ad87153f2f
W1: Document user-scope MCP config location in ~/.claude/CLAUDE.md —
adds verification and re-registration commands, warns against
settings.json (saves ~12K tokens per registration session).
W2: scripts/register_project.sh + make register-project —
5-step automation: API health → topic lookup → MCP check →
CLAUDE.md from template → progress event.
W3: state-hub/scripts/project_claude_md.template —
parameterised CLAUDE.md with {PROJECT_NAME}/{DOMAIN}/{TOPIC_ID}
placeholders; used by register_project.sh.
W4: Add custodian_topic_id + domain to all 6 canon project charters —
lets agents grep for topic IDs without touching the API.
W5: state-hub/mcp_server/TOOLS.md — compact 30-line tool reference
card; replaces reading the full server.py (~350 lines).
W6: Switch .mcp.json to absolute path + PYTHONPATH env so cwd is not
required; add scripts/patch_mcp_cwd.py for post-registration fix.
Update ~/.claude.json to match (cwd kept for belt-and-suspenders).
W7 (SessionStart hook) deferred: no SessionStart hook type in Claude
Code; PreToolUse with empty matcher fires before every tool call.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
58 lines
2.8 KiB
Markdown
58 lines
2.8 KiB
Markdown
# State Hub MCP — Tool Reference Card
|
|
|
|
Quick reference for all 11 tools and 5 resources. Read this instead of `server.py`.
|
|
|
|
## Query Tools (read-only)
|
|
|
|
| Tool | Key Args | When to use |
|
|
|------|----------|-------------|
|
|
| `get_state_summary()` | — | **Session start.** Full snapshot: totals, blocking decisions, blocked tasks, open workstreams, last 20 events. |
|
|
| `get_topic(slug)` | `slug`: e.g. `"markitect"` | Deep-dive on one topic + its workstreams + recent events. |
|
|
| `list_blocked_tasks(workstream_id?)` | optional filter | Surface all impediments, optionally scoped to one workstream. |
|
|
| `list_pending_decisions(topic_id?)` | optional filter | Decisions holding up work, sorted by deadline. |
|
|
| `get_recent_progress(limit, since?)` | `limit` default 20; `since` ISO datetime | Reconstruct recent session history. |
|
|
|
|
## Mutate Tools (each auto-emits a progress_event)
|
|
|
|
| Tool | Key Args | Notes |
|
|
|------|----------|-------|
|
|
| `create_task(workstream_id, title, ...)` | `priority`: low/medium/high/critical; `assignee?`; `due_date?` | Creates task under a workstream. |
|
|
| `update_task_status(task_id, status, ...)` | `status`: todo/in_progress/blocked/done/cancelled; `blocking_reason` required when blocked | |
|
|
| `record_decision(title, ...)` | `decision_type`: made/pending; `topic_id?`; `workstream_id?`; `deadline?` | Financial/legal + pending → auto-escalated per constitution §4. At least one of topic_id/workstream_id required. |
|
|
| `resolve_decision(decision_id, rationale, decided_by)` | all required | Marks decision resolved and records who decided. |
|
|
| `add_progress_event(summary, ...)` | `event_type`: note/milestone/blocker/insight; `topic_id?`; `workstream_id?`; `task_id?`; `detail?` | Append-only log entry. **Use at session end.** |
|
|
| `update_workstream_status(workstream_id, status)` | `status`: active/blocked/completed/archived | |
|
|
|
|
## Resources (URI-addressable, read-only)
|
|
|
|
| URI | Returns |
|
|
|-----|---------|
|
|
| `state://summary` | Full StateSummary JSON |
|
|
| `state://topics` | Active topics list |
|
|
| `state://workstreams/{topic_slug}` | Workstreams for a topic (by slug) |
|
|
| `state://decisions/blocking` | All pending decisions |
|
|
| `state://tasks/blocked` | All blocked tasks |
|
|
|
|
## Domain Slugs
|
|
|
|
`custodian` · `railiance` · `markitect` · `coulomb-social` · `personhood` · `foerster-capabilities`
|
|
|
|
## Common Patterns
|
|
|
|
```python
|
|
# New workstream (via API — no MCP tool yet):
|
|
# POST /workstreams/ {"topic_id": "...", "slug": "...", "title": "...", "status": "active", "owner": "..."}
|
|
|
|
# Session start ritual:
|
|
get_state_summary()
|
|
|
|
# Session end ritual:
|
|
add_progress_event(
|
|
summary="...",
|
|
event_type="note", # or milestone / insight / blocker
|
|
topic_id="<uuid>",
|
|
workstream_id="<uuid>", # optional
|
|
detail={"key": "value"}, # optional structured data
|
|
)
|
|
```
|