Perseus
UnclaimedPerseus Context Engine — resolve verified workspace state before the context window opens. Local-first, MCP-native, MIT.
Install
docker run --rm -v /path/to/workspace:/workspace perseus mcp serveSet up this server
More in AI & ML
Browse the full directoryUnclaimed listing
Is this your MCP server?
This listing was auto-indexed from the public record. Claim it to edit the page, set compatibility and unlock growth tools. Takes under two minutes.
Claim this serverSecurity profile
Claimed and verified servers get a weekly static scan that shows what the code can reach: external services, environment variables, shell commands, agent configuration folders, plus any dependencies with known advisories. Claim this listing to get one. How the security profile works
39 of 39 tools
Documented tools (39)
From project documentation. A server handshake does not verify each tool’s description or behavior.
perseus_agent
Execute local agent subprocess
perseus_agent_projection_preview
Compile a bounded, task-scoped sanitized agent projection. Shows the exact agent view separately from provenance and selection reasons; receipts contain hashes/references only.
perseus_agent_projection_release
Release a previously previewed sanitized projection after matching per-scope consent. Durable release metadata excludes prompts, private bodies, secrets, and tool arguments.
perseus_agora
List tasks from the project task board (tasks/.md files). Use to see what is open, in progress, or completed. Filter by status. Read-only; returns task array with id, title, status, scope.
perseus_auto_skill
Instruct the agent to load a specific skill before starting work. Use at the top of context documents to enforce critical hygiene skills (e.g., memory-hygiene, agent-safety). Renders as a mandatory instruction block. Read-only.
perseus_budget
Declare a token budget for the rendered context (renders as empty text). Enforced by perseus prompt-size: an over-budget render warns — or fails with strict — with a per-directive byte/token breakdown (#606). Declarations are read from source text before conditionals are evaluated; top-level only —
perseus_capture
Write recent session checkpoints to Perseus Vault as durable memories (#713) — the write side of the memory loop, symmetric to @memory recall. Idempotent per checkpoint (re-render upserts, never duplicates). Use at session boundaries so lessons persist immediately instead of waiting for a scheduled
perseus_context_ask
Answer one narrow question from at most 64 scoped records with evidence-linked validity/confidence, or an explicit insufficient-evidence/review/degraded/unavailable outcome.
perseus_context_diff
Render a compact 'Since last session' delta (#714): git branch/commits, Agora task-board changes, new inbox messages, new checkpoints, and new vault session memories since the last recorded snapshot. Use at the top of a context document so the assistant spends zero turns re-orienting on unchanged st
perseus_context_rank
Deterministically rank at most 64 caller-supplied candidates for one task/scope, preserving identity and provenance commitments without exporting raw private memory.
perseus_date
Current date/time
perseus_drift
Detect drift between predicted and actual tool usage patterns via the Guide oracle. Use when tool behavior seems off or after config changes. For workspace hygiene checks, prefer perseushealth. Read-only; returns a markdown drift report.
perseus_env
Embed environment variable
perseus_focus
The global-workspace tier: a small, capacity-bounded (default 32), salience-ranked set of items Perseus broadcasts into context — the shared 'what I'm working on now' set for the agent and its subagents. With no args, renders the current working set. add=/pin= admit items; the lowest-salience non-pi
perseus_get_context
Return the full rendered Perseus context for the workspace.
perseus_get_health
Run Daedalus context-maintenance heuristics — cache health, directive resolution stats, memory integrity check. mode=basic (default) returns the @health maintenance report; mode=doctor returns the same structured payload as perseus doctor --json (per-check status + summary), the MCP equivalent of th
perseus_health
Audit workspace context health: stale skills, duplicate tasks, oversized output. Use before starting work to catch drift. For deep Daedalus heuristics (cache, directive stats), use perseusgethealth. Read-only; returns status enum and metric counts.
perseus_inbox
Read agent-to-agent messages from the workspace inbox. Use to check for coordination messages from other agents. Filter to unread only. Read-only; returns message array with read/unread status.
perseus_include
Include and render another Perseus source file, recursively resolving its directives. Use to compose context from multiple files or share common sections across workspaces. Bound a growing file with last=N (final N lines) or since=14d/2w/24h (recent dated sections only). Use mode=reference (or rende
perseus_list
List directory contents or structured data. Use to discover files before reading with perseusread. Supports sorting by name, modified time, or size. Read-only; for hierarchical view, prefer perseustree.
perseus_mason
Query the Mason code architecture concept map to find which files implement a feature. Use before editing code to understand where changes should go. Read-only; returns concept map and mapped file list.
perseus_memory
Search LOCAL project memory (FTS5, zero-network) for past decisions and architecture notes. Use for in-workspace recall. For cross-session persistent facts, use perseusvault instead. Read-only; returns results array with mode and count.
perseus_perseus
Fetch rendered context from a remote Perseus instance by URL. Use to pull live workspace state from another machine or container. Read-only; caches results — re-fetch when remote state may have changed.
perseus_profile
Select the per-model context profile for this document (#608): sets the context target and memory posture (ondemand/relevant/always) used by the automatic memory injection layer. Use at the top of a context document, e.g. @profile claude-sonnet-4-6. Unknown names fall back to the default profile. Fi
perseus_prompt
Define a system prompt block that instructs the AI assistant about how to use the rendered context. Use to set behavioral rules, memory hygiene gates, or context interpretation guidelines. Read-only; rendered as-is into the output.
perseus_query
Run a shell command and return stdout
perseus_read
Read and embed file contents into the rendered context. Use to inject config values, environment files, or any text file. Can extract specific keys from structured files. Read-only; use perseuslist or perseustree to browse before reading.
perseus_research
Search an EXTERNAL paper-search MCP server (BGPT by default) for scientific literature and inject per-paper Methods/Results blocks. Use to ground claims in published studies. Self-gates on research.enabled; degrades gracefully when the provider is unreachable. Read-only; speaks JSON-RPC over stdio (
perseus_services
Health-check all services listed in the workspace context (HTTP endpoints, Docker containers, shell commands). Use to verify the environment is healthy before starting work. May make network calls and execute shell commands per service definition — side effects depend on configured checks.
perseus_session
List recent session digests with task summaries and outcomes. Use to understand what was done recently across sessions. For the single most recent checkpoint, prefer perseuswaypoint. Read-only; returns session array with count.
perseus_skill_candidates
List mined procedural-skill candidates (from session transcripts) pending operator review: trigger, steps, pitfalls, evidence sessions, token cost. Candidates are staged, never active — perseus skills approve <name> promotes one to the live skills dir. Opt-in surfacing: place the directive in your c
perseus_skills
List available skills with descriptions and freshness status. Use to discover what capabilities are installed. Filter by category for smaller output. Read-only; stale skills flagged automatically.
perseus_tokens
Embed token budget for rendered context
perseus_tool
Run an external tool that has been allowlisted in the Perseus configuration. Use for approved integrations only. Requires the tool name to be present in the allowlist. Destructive — executes the tool with the user's permissions.
perseus_tooltrim
Return filtered toolset metadata and usage statistics. Use to understand what tools are available and how they are being used. For full tool metadata, set full=true. Read-only; stats mode returns aggregated counts.
perseus_tree
Display a directory tree with configurable depth. Use to understand project structure at a glance. For flat file listings with metadata, use perseuslist instead. Read-only; depth limits control output size.
perseus_validate
Validate a rendered block against a JSON Schema. Use to enforce structure on configuration blocks, task definitions, or any schema-constrained section. Read-only; returns pass/fail with error messages.
perseus_vault
Query Perseus Vault for scoped, durable context. Read-only; falls back to the local Vault FTS5 index when the service is unavailable.
perseus_waypoint
Return the most recent session checkpoint: what was being worked on, status, and next steps. Use at session start to resume where you left off. Stale after TTL (default 24h). Read-only; lightweight — call freely.
Tool change history
FAQ
Questions about Perseus MCP Server
- How do I connect Perseus MCP Server to Claude?
- The listing records `docker run --rm -v /path/to/workspace:/workspace perseus mcp serve` as its setup step. Run it, then follow the repository's instructions for the client configuration; the listing names Claude Desktop, Claude Code, Cursor as compatible clients.
- Is Perseus MCP Server free?
- The listed licence is MIT. Check the upstream terms for permitted use and commercial requirements; a public repository does not by itself mean the software is free or open source. Connected APIs and hosted services may have separate charges.
- What can Perseus MCP Server do?
- Perseus MCP Server documents 39 tools to the agent, including perseus_agent, perseus_agent_projection_preview, perseus_agent_projection_release. The descriptions above come from project documentation. A live handshake does not test individual tool behavior.