Igor Lins e Silva
107685930d
The regression-guard tests added in #835 were pinned to the old README shape (tool table + file-reference table). When #897 slimmed the README and moved that content to the website, three tests started failing: TestReadmeToolsExistInCode.test_every_readme_tool_exists_in_tools_dict TestNoUnlistedTools.test_no_undocumented_tools TestReadmeDialectNotLossless.test_readme_dialect_line_not_lossless Changes in this commit: 1. Update the 3 tests to track the new canonical docs surfaces - Tool list -> website/reference/mcp-tools.md (tests parse `### \`mempalace_xxx\`` headings instead of markdown table rows). - dialect.py lossless disclaimer -> website/reference/modules.md (any line mentioning dialect.py must not also say "lossless"). 2. Fix the website to make "no undocumented tools" true Add the 10 tools that existed in TOOLS but were missing from website/reference/mcp-tools.md (create_tunnel, delete_tunnel, follow_tunnels, list_tunnels, get_drawer, list_drawers, update_drawer, hook_settings, memories_filed_away, reconnect). Page header now correctly says "all 29 MCP tools". 3. Align pre-commit ruff pin to match CI (0.4.x) .pre-commit-config.yaml was pinning ruff v0.9.0, while .github/workflows/ci.yml installs ruff>=0.4.0,<0.5. The two formatters produce incompatible output (e.g. v0.9.0 reformats `assert (x), msg` -> `assert x, (msg)` in a way v0.4.x rejects), which would cause the pre-commit hook to modify files that CI then flags as unformatted. Pinning the hook to v0.4.10 keeps the dev loop and CI in lock-step. Full suite: 887 passed, 0 failed.
382 lines
11 KiB
Markdown
382 lines
11 KiB
Markdown
# MCP Tools Reference
|
||
|
||
Detailed parameter schemas for all 29 MCP tools.
|
||
|
||
## Palace — Read Tools
|
||
|
||
### `mempalace_status`
|
||
|
||
Palace overview: total drawers, wing and room counts, AAAK spec, and memory protocol.
|
||
|
||
**Parameters:** None
|
||
|
||
**Returns:** `{ total_drawers, wings, rooms, palace_path, protocol, aaak_dialect }`
|
||
|
||
---
|
||
|
||
### `mempalace_list_wings`
|
||
|
||
List all wings with drawer counts.
|
||
|
||
**Parameters:** None
|
||
|
||
**Returns:** `{ wings: { "wing_name": count } }`
|
||
|
||
---
|
||
|
||
### `mempalace_list_rooms`
|
||
|
||
List rooms within a wing (or all rooms if no wing given).
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `wing` | string | No | Wing to list rooms for |
|
||
|
||
**Returns:** `{ wing, rooms: { "room_name": count } }`
|
||
|
||
---
|
||
|
||
### `mempalace_get_taxonomy`
|
||
|
||
Full wing → room → drawer count tree.
|
||
|
||
**Parameters:** None
|
||
|
||
**Returns:** `{ taxonomy: { "wing": { "room": count } } }`
|
||
|
||
---
|
||
|
||
### `mempalace_search`
|
||
|
||
Semantic search. Returns verbatim drawer content with similarity scores.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `query` | string | **Yes** | What to search for |
|
||
| `limit` | integer | No | Max results (default: 5) |
|
||
| `wing` | string | No | Filter by wing |
|
||
| `room` | string | No | Filter by room |
|
||
|
||
**Returns:** `{ query, filters, results: [{ text, wing, room, source_file, similarity }] }`
|
||
|
||
---
|
||
|
||
### `mempalace_check_duplicate`
|
||
|
||
Check if content already exists in the palace before filing.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `content` | string | **Yes** | Content to check |
|
||
| `threshold` | number | No | Similarity threshold 0–1 (default: 0.85–0.87) |
|
||
|
||
**Returns:** `{ is_duplicate, matches: [{ id, wing, room, similarity, content }] }`
|
||
|
||
---
|
||
|
||
### `mempalace_get_aaak_spec`
|
||
|
||
Returns the AAAK dialect specification.
|
||
|
||
**Parameters:** None
|
||
|
||
**Returns:** `{ aaak_spec: "..." }`
|
||
|
||
---
|
||
|
||
## Palace — Write Tools
|
||
|
||
### `mempalace_add_drawer`
|
||
|
||
File verbatim content into the palace. Identical content (same deterministic drawer ID) is silently skipped. For similarity-based duplicate detection before filing, use `mempalace_check_duplicate`.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `wing` | string | **Yes** | Wing (project name) |
|
||
| `room` | string | **Yes** | Room (aspect: backend, decisions, etc.) |
|
||
| `content` | string | **Yes** | Verbatim content to store |
|
||
| `source_file` | string | No | Where this came from |
|
||
| `added_by` | string | No | Who is filing (default: "mcp") |
|
||
|
||
**Returns:** `{ success, drawer_id, wing, room }`
|
||
|
||
---
|
||
|
||
### `mempalace_delete_drawer`
|
||
|
||
Delete a drawer by ID. Irreversible.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `drawer_id` | string | **Yes** | ID of the drawer to delete |
|
||
|
||
**Returns:** `{ success, drawer_id }`
|
||
|
||
---
|
||
|
||
### `mempalace_get_drawer`
|
||
|
||
Fetch a single drawer by ID — returns full content and metadata.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `drawer_id` | string | **Yes** | ID of the drawer to fetch |
|
||
|
||
**Returns:** `{ drawer: { id, wing, room, content, ... } }`
|
||
|
||
---
|
||
|
||
### `mempalace_list_drawers`
|
||
|
||
List drawers with pagination. Optional wing/room filter. Returns IDs, wings, rooms, and content previews.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `wing` | string | No | Filter by wing |
|
||
| `room` | string | No | Filter by room |
|
||
| `limit` | integer | No | Max results per page (default 20, max 100) |
|
||
| `offset` | integer | No | Offset for pagination (default 0) |
|
||
|
||
**Returns:** `{ drawers: [...], total, limit, offset }`
|
||
|
||
---
|
||
|
||
### `mempalace_update_drawer`
|
||
|
||
Update an existing drawer's content and/or metadata (wing, room). Fetches the existing drawer first; returns an error if not found.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `drawer_id` | string | **Yes** | ID of the drawer to update |
|
||
| `content` | string | No | New content (omit to keep existing) |
|
||
| `wing` | string | No | New wing (omit to keep existing) |
|
||
| `room` | string | No | New room (omit to keep existing) |
|
||
|
||
**Returns:** `{ success, drawer_id, updated_fields }`
|
||
|
||
---
|
||
|
||
## Knowledge Graph Tools
|
||
|
||
### `mempalace_kg_query`
|
||
|
||
Query entity relationships with time filtering.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `entity` | string | **Yes** | Entity to query (e.g. "Max", "MyProject") |
|
||
| `as_of` | string | No | Date filter — only facts valid at this date (YYYY-MM-DD) |
|
||
| `direction` | string | No | `outgoing`, `incoming`, or `both` (default: `both`) |
|
||
|
||
**Returns:** `{ entity, as_of, facts: [{ direction, subject, predicate, object, valid_from, valid_to, current }], count }`
|
||
|
||
---
|
||
|
||
### `mempalace_kg_add`
|
||
|
||
Add a fact to the knowledge graph.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `subject` | string | **Yes** | The entity doing/being something |
|
||
| `predicate` | string | **Yes** | Relationship type (e.g. "loves", "works_on") |
|
||
| `object` | string | **Yes** | The entity being connected to |
|
||
| `valid_from` | string | No | When this became true (YYYY-MM-DD) |
|
||
| `source_closet` | string | No | Closet ID where this fact appears |
|
||
|
||
**Returns:** `{ success, triple_id, fact }`
|
||
|
||
---
|
||
|
||
### `mempalace_kg_invalidate`
|
||
|
||
Mark a fact as no longer true.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `subject` | string | **Yes** | Entity |
|
||
| `predicate` | string | **Yes** | Relationship |
|
||
| `object` | string | **Yes** | Connected entity |
|
||
| `ended` | string | No | When it stopped being true (default: today) |
|
||
|
||
**Returns:** `{ success, fact, ended }`
|
||
|
||
---
|
||
|
||
### `mempalace_kg_timeline`
|
||
|
||
Chronological timeline of facts.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `entity` | string | No | Entity to get timeline for (omit for full timeline) |
|
||
|
||
**Returns:** `{ entity, timeline: [{ subject, predicate, object, valid_from, valid_to, current }], count }`
|
||
|
||
---
|
||
|
||
### `mempalace_kg_stats`
|
||
|
||
Knowledge graph overview.
|
||
|
||
**Parameters:** None
|
||
|
||
**Returns:** `{ entities, triples, current_facts, expired_facts, relationship_types }`
|
||
|
||
---
|
||
|
||
## Navigation Tools
|
||
|
||
### `mempalace_traverse`
|
||
|
||
Walk the palace graph from a room. Find connected ideas across wings.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `start_room` | string | **Yes** | Room to start from |
|
||
| `max_hops` | integer | No | How many connections to follow (default: 2) |
|
||
|
||
**Returns:** `[{ room, wings, halls, count, hop, connected_via }]`
|
||
|
||
---
|
||
|
||
### `mempalace_find_tunnels`
|
||
|
||
Find rooms that bridge two wings.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `wing_a` | string | No | First wing |
|
||
| `wing_b` | string | No | Second wing |
|
||
|
||
**Returns:** `[{ room, wings, halls, count, recent }]`
|
||
|
||
---
|
||
|
||
### `mempalace_graph_stats`
|
||
|
||
Palace graph overview: nodes, tunnels, edges, connectivity.
|
||
|
||
**Parameters:** None
|
||
|
||
**Returns:** `{ total_rooms, tunnel_rooms, total_edges, rooms_per_wing, top_tunnels }`
|
||
|
||
---
|
||
|
||
### `mempalace_create_tunnel`
|
||
|
||
Create a cross-wing tunnel linking two palace locations. Use when content in one project relates to another — e.g., an API design in `project_api` connects to a database schema in `project_database`.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `source_wing` | string | **Yes** | Wing of the source |
|
||
| `source_room` | string | **Yes** | Room in the source wing |
|
||
| `target_wing` | string | **Yes** | Wing of the target |
|
||
| `target_room` | string | **Yes** | Room in the target wing |
|
||
| `label` | string | No | Description of the connection |
|
||
| `source_drawer_id` | string | No | Specific source drawer ID |
|
||
| `target_drawer_id` | string | No | Specific target drawer ID |
|
||
|
||
**Returns:** `{ success, tunnel_id, source, target }`
|
||
|
||
---
|
||
|
||
### `mempalace_list_tunnels`
|
||
|
||
List all explicit cross-wing tunnels. Optionally filter by wing.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `wing` | string | No | Filter tunnels by wing (source or target) |
|
||
|
||
**Returns:** `{ tunnels: [...], count }`
|
||
|
||
---
|
||
|
||
### `mempalace_delete_tunnel`
|
||
|
||
Delete an explicit tunnel by its ID.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `tunnel_id` | string | **Yes** | Tunnel ID to delete |
|
||
|
||
**Returns:** `{ success, tunnel_id }`
|
||
|
||
---
|
||
|
||
### `mempalace_follow_tunnels`
|
||
|
||
Follow tunnels from a room to see what it connects to in other wings. Returns connected rooms with drawer previews.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `wing` | string | **Yes** | Wing to start from |
|
||
| `room` | string | **Yes** | Room to follow tunnels from |
|
||
|
||
**Returns:** `[{ wing, room, label, previews }]`
|
||
|
||
---
|
||
|
||
## Agent Diary Tools
|
||
|
||
### `mempalace_diary_write`
|
||
|
||
Write to your personal agent diary.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `agent_name` | string | **Yes** | Your name — each agent gets its own wing |
|
||
| `entry` | string | **Yes** | Diary entry (in AAAK format recommended) |
|
||
| `topic` | string | No | Topic tag (default: "general") |
|
||
|
||
**Returns:** `{ success, entry_id, agent, topic, timestamp }`
|
||
|
||
---
|
||
|
||
### `mempalace_diary_read`
|
||
|
||
Read recent diary entries.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `agent_name` | string | **Yes** | Your name |
|
||
| `last_n` | integer | No | Number of recent entries (default: 10) |
|
||
|
||
**Returns:** `{ agent, entries: [{ date, timestamp, topic, content }], total, showing }`
|
||
|
||
---
|
||
|
||
## System Tools
|
||
|
||
### `mempalace_hook_settings`
|
||
|
||
Get or set auto-save hook behaviour. `silent_save=true` saves directly without MCP-level clutter; `silent_save=false` uses the legacy blocking path. `desktop_toast=true` surfaces a desktop notification when a save completes. Call with no arguments to view the current settings.
|
||
|
||
| Parameter | Type | Required | Description |
|
||
|-----------|------|----------|-------------|
|
||
| `silent_save` | boolean | No | `true` = silent direct save, `false` = blocking MCP calls |
|
||
| `desktop_toast` | boolean | No | `true` = show desktop toast via `notify-send` |
|
||
|
||
**Returns:** `{ silent_save, desktop_toast }`
|
||
|
||
---
|
||
|
||
### `mempalace_memories_filed_away`
|
||
|
||
Check whether a recent palace checkpoint was saved. Returns message count and timestamp of the last save.
|
||
|
||
**Parameters:** None
|
||
|
||
**Returns:** `{ filed, message_count, timestamp }`
|
||
|
||
---
|
||
|
||
### `mempalace_reconnect`
|
||
|
||
Force a reconnect to the palace database. Use this after external scripts or CLI commands modified the palace directly, which can leave the in-memory HNSW index stale.
|
||
|
||
**Parameters:** None
|
||
|
||
**Returns:** `{ success, palace_path }`
|