/mcp-tools

name: mcp-tools
description: "MCP tool decision tree and MCP-first fallback strategy. TRIGGER when: choosing whether to use an MCP tool versus a built-in, or an MCP tool is available for a task. SKIP: semantic-memory MCP usage specifically (use semantic-memory-mcp)."

MCP Tools Decision Tree

Priority Order

1. Does an MCP tool exist for this operation? **Use it first.** 2. Did the MCP tool fail (auth missing, plugin unavailable)? **Fall back to built-in.** 3. No MCP tool matches? **Use built-in tools** (Bash, Grep, WebSearch, etc.).

MCP Plugin Quick Reference

| Plugin | Transport | Key Tools | Agents | |--------|-----------|-----------|--------| | context7 | stdio | `mcp__context7__resolve-library-id`, `mcp__context7__get-library-docs` | researcher, developer | | playwright | stdio | `mcp__playwright__browser_navigate`, `mcp__playwright__browser_screenshot` | developer, debugger | | eslint | stdio | `mcp__eslint__*` | developer, reviewer | | sonarqube | docker | `mcp__sonarqube__*` | developer, reviewer | | sequential-thinking | stdio | `mcp__sequential-thinking__*` | architect, debugger | | postgres-mcp | stdio | `mcp__postgres-mcp__*` | developer, optimizer | | redis-mcp | stdio | `mcp__redis-mcp__*` | developer, devops, debugger | | docker | stdio | `mcp__docker__*` | devops | | cron | stdio | `mcp__cron__*` | devops | | ssh-mcp | stdio | `mcp__ssh-mcp__*` | devops | | github | http | `mcp__github__*` | gitops, architect | | google-sheets | stdio | `mcp__google-sheets__*` | researcher, tech-writer | | slack | sse | `mcp__slack__*` | tech-writer | | asana | sse | `mcp__asana__*` | architect | | supabase | http | `mcp__supabase__*` | optimizer | | firebase | stdio | `mcp__firebase__*` | devops, optimizer | | memory | stdio | 13 tools across search/store/notes/ingest/session tiers (see below) | tiered — see Access Control |

Semantic Memory MCP

• **Transport**: stdio (Python, `venv/bin/python -m mcp_servers.semantic_memory`)
• **Source**: MCP servers in your backend directory (internal, built on `fastmcp`)
• **Auth**: `DATABASE_URL` (PostgreSQL connection string), `SEMANTIC_MEMORY_ENABLED=true`
• **Config**: `.mcp.json` at project root

Tools (13 total)

| Tool | Purpose | Parameters | |------|---------|------------| | `search_context` | Search ingested context chunks (Qdrant hybrid retrieval) | `query` (required), `corpus`, `top_k` | | `semantic_search` | Search memories by similarity | `query` (required), `project_id`, `agent_name`, `top_k`, `threshold` | | `semantic_recall` | Recall relevant memories as markdown | `context` (required), `agent_name`, `project_id`, `top_k` | | `semantic_store` | Store a new memory with embedding | `content` (required), `agent_name` (required), `project_id`, `conversation_id`, `task_id`, `tags`, `content_type` | | `store_note` | Persist a note document | `corpus`, `relative_path`, `content` (see notes-tier agents) | | `read_note` | Read a note document | `corpus`, `relative_path` | | `list_notes` | List note documents | `corpus` | | `trigger_ingest` | Queue ONE document (`corpus` + `relative_path`) for immediate re-indexing so a note just written via `store_note` becomes searchable in seconds instead of up to 15 minutes. Path-scoped only — cannot trigger a full backfill. Returns once queued; does not wait for indexing to finish (~3s to become searchable). Only useful to agents that also have `store_note` — otherwise you'd be re-indexing someone else's file. | `corpus` (required), `relative_path` (required) | | `list_sessions` | List memory sessions (catalog) | — | | `get_session` | Get a session's details | `session_id` | | `semantic_list` | List stored memories (catalog) | `project_id` | | `semantic_delete` | Delete a memory | `memory_id` (granted to no agent) | | `archive_session` | Archive a session | `session_id` (granted to no agent) |

Access Control

| Tier | Tools | Agents | |------|-------|--------| | Write (search/recall/store) | `search_context`, `semantic_search`, `semantic_recall`, `semantic_store` | developer, architect, debugger, analyst, researcher, reviewer, optimizer | | Read-only | `search_context`, `semantic_search`, `semantic_recall` | tech-writer, devops, gitops, mcp-builder, prompt-engineer | | Notes | `store_note`, `read_note`, `list_notes` | architect, researcher | | Ingest trigger | `trigger_ingest` | architect, researcher — narrow grant, restricted to the two agents that also hold `store_note`; broader access would invite wasted LLM context-gen calls re-indexing files the caller didn't write | | Session catalog | `list_sessions`, `get_session`, `semantic_list` | coordinator | | Delete/archive | `semantic_delete`, `archive_session` | nobody |

`corpus` (top-level NFS share directory: `homelab`, `platform`, `projects`) and `project_id` (`scaffold:<hash>`, one per repo) are different axes — `corpus` scopes the notes/ingest tools above, `project_id` scopes the `semantic_*` (mem0) tools. Don't pass one where the other is expected.

For detailed usage guidance (when to search, when to store, quality gates), see the `semantic-memory-mcp` skill.

Fallback Strategy

| Operation | MCP Tool (Priority) | Fallback | |-----------|---------------------|----------| | Library docs lookup | context7 | WebSearch | | UI verification | playwright | Manual browser check | | Code quality | sonarqube | `python3 devops/sonarqube.py` via Bash | | Linting | eslint | `npx eslint` via Bash | | Database query | postgres-mcp | `psql` via Bash | | Cache inspection | redis-mcp | `redis-cli` via Bash | | Container ops | docker | `docker` via Bash | | Git operations | github | `gh` CLI via Bash | | Memory search | memory | File-based agent-memory | | Remote server | ssh-mcp | `ssh` via Bash |