studiosystem-mcp

MCP server for Studio System — a thin, safety-first REST adapter that lets AI clients (Claude, Kimi Work, Cursor, WorkBuddy…) work with your Studio instance:

• Mind maps (use cases): list folders/maps, read a map as a text outline instead of raw JSON

• Tasks: list/query tasks, lists, tags, filters with high-level semantics

• Wiki: vaults, page tree, read pages, full-text search / backlinks / graph

It talks to the existing /api/v1 REST API over HTTP — no database access, no backend code changes — and inherits the backend's JWT + RBAC permissions.

⚠️ This server holds writable credentials. Run it in a trusted environment. For read-only exploration set STUDIO_MCP_READ_ONLY=true.

Quick start

Not on PyPI yet — install straight from this repo with uv:

# stdio (local client integration)
uvx --from git+https://github.com/088729/studiosystem-mcp studiosystem-mcp

# or HTTP transport
uvx --from git+https://github.com/088729/studiosystem-mcp studiosystem-mcp --transport http --port 8303

Minimal client config (e.g. Claude Desktop / Kimi Work):

{
  "mcpServers": {
    "studio": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/088729/studiosystem-mcp",
        "studiosystem-mcp"
      ],
      "env": {
        "STUDIO_BASE_URL": "http://127.0.0.1:8302",
        "STUDIO_MCP_AUTH_MODE": "password",
        "STUDIO_MCP_USERNAME": "mcp-bot",
        "STUDIO_MCP_PASSWORD": "your-password"
      }
    }
  }
}

Remote HTTP mode:

{
  "mcpServers": {
    "studio": {
      "url": "http://your-host:8303/mcp",
      "headers": { "Authorization": "Bearer <mcp-token>" }
    }
  }
}

Related MCP server: manager-full-mcp

Authentication modes (STUDIO_MCP_AUTH_MODE)

Use a dedicated least-privilege service account (e.g. mcp-bot with the viewer role plus explicit extra_permissions) — never admin. See .env.example and config.example.yaml for the full configuration surface.

Configuration

Three layers, highest wins: environment variables (STUDIO_MCP_*) → config.yaml (path in STUDIO_MCP_CONFIG) → built-in defaults. See .env.example and config.example.yaml for the full list.

Key knobs:

Tools

System: studio_status, studio_capabilities, whoami (permissions self-check)

Case: read — case_list_folders, case_list_maps, case_get_map (text outline, source=draft|published|version:N); write — case_create_map (outline→tree), case_edit_map (node patches add/update/delete/move; lock→read→version-CAS→snapshot→unlock closed loop; forced two-phase confirm), case_save_draft (async draft), case_versions (list / rollback; rollback requires ALLOW_DESTRUCTIVE + confirm)

Task: read — task_list_context, task_list_tasks, task_get_task; write — task_create (quick-add @明天 !高 ~回归 #清单 + idempotency key), task_update (PATCH fields / action=complete|uncomplete|skip), task_delete (soft|restore|purge; purge requires ALLOW_DESTRUCTIVE + confirm), task_batch (forced confirm)

Wiki: read — wiki_list_vaults, wiki_tree, wiki_read_page, wiki_search (search / backlinks / graph); write (P2) — wiki_create_page (409-safe one step), wiki_write_page (read-before-write + diff preview + lock→PUT→explicit commit→release; forced confirm; refuses blind overwrite), wiki_history (list|diff|revert; revert requires ALLOW_DESTRUCTIVE + confirm)

Analytics / Focus / Habits: read — task_overview, task_summary_markdown (日报/周报素材), focus_status, focus_report, habit_today, habit_week, habit_stats; write (P2, one step) — focus_start, focus_pause, focus_resume, focus_finish, focus_abandon, habit_checkin, habit_skip, habit_un_checkin

Git (P2): vault_status, page_history, page_diff, page_revert (requires ALLOW_DESTRUCTIVE + confirm), vault_pull / vault_push (confirm; push also ALLOW_DESTRUCTIVE), vault_commit (confirm, custom message), wiki_reindex (async; poll vault_status.rebuild)

Collab (P2): task_comment (list|add), calendar_range, pending_reminders, reminder_ack (ack / snooze), share_members (list|add)

Workflow (P2): generate_wiki_from_tasks (summary → Jinja2 → page + commit), generate_wiki_from_case (map outline → testcase_spec + backlinks), case_outline_to_tasks (leaf nodes → tasks with case_map_id/case_node_id backfill; forced confirm)

Prompts (P2): weekly_report, testcase_spec, retro, case_review, standup — safety-constrained prompt templates (preview diff before any write).

Admin (P3, default OFF): admin_user_list / admin_role_list / admin_permission_list (read); admin_user_create / admin_user_update (permissions|active|job_scope) / admin_user_delete / admin_batch_permissions / admin_role_create / admin_role_update / admin_role_delete / admin_permission_create / admin_permission_delete (all forced-confirm). Triple-gated: ALLOW_ADMIN=true + READ_ONLY=false + backend sys:manage. Client-side guardrails: cannot delete/deactivate the currently authenticated user; passwords are masked in audit logs and never echoed in previews/results. Treat this domain as holding the keys to the kingdom — enable only for admin scenarios, and prefer a least-privilege mcp-bot account for everyday use.

Write tools follow risk-tiered confirmation (Q4): irreversible/whole-tree operations (case_edit_map, rollback, purge, batch) return a preview + confirm_token and execute only when the token is presented; low-risk operations run in one step (dry_run=true previews). STUDIO_MCP_CONFIRM_MODE=none disables forced confirmation for unattended pipelines.

Design notes

• Semantic traps are absorbed here, not exposed to the model: draft-vs-snapshot duality, whole-tree overwrite on save, 1-minute edit lock TTL, due_at field names, last-write-wins APIs.

• Error normalization: backend {"detail": {"code","message"}} becomes a readable message + code + suggested action.

• Protocol versions: targets MCP 2026-07-28 with 2025-11-25 as compatibility baseline; capabilities are declared via server/discover when the client requests it, with graceful degradation.

• Auditing: every call is logged as JSONL (credentials masked).

Development

uv venv .venv && uv pip install -e ".[dev]"
pytest            # uses httpx.MockTransport — no real backend needed
ruff check .
python scripts/zero_residue_scan.py   # internal-value leak gate (runs in CI too)

Release

Tag-driven (.github/workflows/release.yml): pushing a vX.Y.Z tag whose version matches pyproject.toml runs CI — ruff, zero-residue scan, pytest, wheel build, and an offline smoke-install of the built wheel. The final PyPI publish step ships commented out until trusted publishing is configured on PyPI (pending publisher: this repo, release.yml); until then install from git as shown above. Protocol compatibility is guarded by a dedicated CI job running tests/test_protocol_matrix.py against both supported protocol versions (2026-07-28 / 2025-11-25).

Security

See SECURITY.md. Reporting: please open an issue labeled security.

License

MIT — see LICENSE.