MCP Tools

MCP Tools (38 tools)

The same tools are available to the chat UI, Cursor, Windsurf, or any MCP-compatible agent.

All tools are registered in mcp/index.js. Each tool file in mcp/tools/ exports a register(server, ctx) function.

---

Memory (7 tools) — memory.js

Tool	Description
remember	Save a new memory with auto-generated embeddings for semantic search. Supports types: fact, preference, project, decision, solution, source, person.
propose_memory	Propose a memory for user review (goes to inbox instead of being saved directly).
recall	Search memories via semantic similarity, full-text, or auto mode. Filter by type, tags, importance, tier, language.
update_memory	Edit an existing memory by UUID. Previous version is tombstoned.
forget	Delete a memory by UUID.
backfill_embeddings	Generate embeddings for memories that don't have one yet.
deduplicate_memories	Find near-duplicates via cosine similarity — merge or report.

Self-Memory (4 tools) — self-memory.js

Tool	Description
self_remember	Save to the agent's own memory store (its identity, preferences, capabilities).
self_recall	Search the agent's own memory.
self_update	Update an entry in the agent's own memory.
self_forget	Delete from the agent's own memory.

Self-Wiki (2 tools) — self-wiki.js

Tool	Description
self_wiki_write	Write a wiki article in the agent's own knowledge base.
self_wiki_get	Read a wiki article from the agent's own knowledge base.

Files (10 tools) — files.js

Tool	Description
read_file	Read any file from disk (max 500 lines by default, supports chunked reads up to 10k lines).
grep_files	Search files for a regex pattern with context lines.
write_file	Overwrite a file completely (subject to write-path guard).
append_file	Add content to the end of a file without touching the rest.
edit_file	Replace exact text in a file (fuzzy matching fallback).
read_docx	Read and extract text from .docx files.
scan_project	Traverse a project folder — returns file tree and reads key files.
delete_file	Delete a file by path (subject to write-path guard).
generate_xlsx	Generate a multi-sheet .xlsx workbook, served for download.
generate_docx	Create .docx Word documents programmatically.

Web (2 tools) — web.js

Tool	Description
fetch_url	Fetch a URL, strip HTML, truncate at 15 000 characters.
web_search	Search the web via DuckDuckGo (configurable backend), return ranked results.

Image (3 tools) — image.js

Tool	Description
read_image	Load an image (file path or base64) for the agent to analyze.
preprocess_image	Normalize an image to RGB PNG before sending to a local VLM (strips alpha, letterboxes to 896×896).
describe_image	Send an image to a local llama.cpp vision model and return a text description.

Shell (4 tools) — shell.js

Tool	Description
run_shell	Execute a shell command with output capture (off by default, enable with APERIO_ENABLE_SHELL=on).
run_node_script	Run a .js script inside an allowed write path; returns its output.
run_python_script	Run a .py script inside an allowed write path; returns its output.
syntax_check	Check a JavaScript file for syntax errors without executing it.

Wiki (5 tools) — wiki.js

Tool	Description
wiki_write	Create or update a wiki article (upsert by slug, with synthesis from linked memories).
wiki_search	Hybrid search wiki articles by topic (title/summary/body).
wiki_list	List articles newest-first with filters (tag, status, date).
wiki_get	Fetch full article by slug (supports stale check and auto-refresh).
propose_wiki	Propose a wiki article draft for user review.

Code Graph (6 tools) — codegraph.js

Tool	Description
code_search	Search indexed code graph for symbols by name or documentation.
code_repos	List all indexed repos with file and symbol counts.
code_outline	List all symbols in a file with line ranges.
code_context	Fetch source slice for a symbol by qualified name.
code_callers	Find callers of a symbol (depth up to 5).
code_callees	Find callees of a symbol (depth up to 5).

Doc Graph (5 tools) — docgraph.js

Tool	Description
doc_search	Search indexed document graph (notes, reports, plain text) by meaning or keyword.
doc_repos	List indexed folders with document/chunk counts and MIME breakdown.
doc_outline	Return section tree (table of contents) for one document.
doc_context	Fetch text of one section or chunk by ID.
doc_refs	Find documents referencing a specific ID, URL, email, or citation key.

GitHub (5 tools) — github.js

Tool	Description
fetch_github_issue	Fetch an issue by URL (title, state, labels, body, comments, optional images).
create_github_issue	Create an issue (confirm-before-write; resolves project name to repo).
update_github_issue	Comment on and/or update an issue (close/reopen, edit title/body/labels/assignees).
list_github_issues	List open issues for triage across repos.
record_issue_triage	Record a triage verdict in the local ledger (no GitHub write).

Data (2 tools) — data.js

Tool	Description
export_data	Export all memories and wiki articles to portable JSON (no embeddings).
import_data	Import from a previous JSON export (idempotent by ID/slug).

Database (4 tools) — database.js

Tool	Description
db_connections	List available external database connections (never exposes credentials).
db_schema	Introspect tables, columns, indexes, and foreign keys.
db_query	Run ONE read-only SQL statement with parameterized bindings.
db_execute	Propose a write/DDL statement — confirm-before-write flow.

---

Large tool results

When a tool returns more content than the model can safely keep in context, Aperio stores the result in a private artifact and gives the model a bounded preview. The read_artifact tool (auto-attached) lets the agent page through the full result.

---

Raising limits

In mcp/index.js:

const READ_FILE_CHUNK_SIZE = 500;    // max lines per read_file call
const READ_FILE_MAX_OFFSET = 10_000; // safety ceiling for chunked reads

Change these to whatever your use case needs.

---

Example prompts that just work

• "Remember that I use VS Code with the One Dark Pro theme."
• "What do I know about TypeScript?"
• "Read my server.js and tell me what the WebSocket handler does."
• "Scan my project and give me an overview of the structure."
• "Search the web for the latest Node.js release."
• "Create a GitHub issue titled 'Add dark mode' on myproject."
• "Export my memories and wiki to backup.json."

[Back to top ↑]