satori
ham-zax/satori
Agent-safe code retrieval for MCP coding agents: runtime-first search, exact reads, call graph context, and fresh repo evidence before edits.
Instalação
npx convez-ai ham-zax/satori1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Satori
Agent-safe code retrieval for developers who use MCP coding agents on real repos.
Satori indexes a repository, keeps the index fresh, and gives agents a fixed six-tool MCP surface for finding code, opening exact spans, checking callers/callees, and reading bounded evidence before an edit. It is read-only from MCP: source edits stay in your editor or agent host.
What You Get
- Find behavior by intent, not just filenames or exact tokens.
- Keep search focused on runtime code before pulling in docs or tests.
- Open exact files, line ranges, and symbols instead of dumping broad context.
- Trace nearby callers/callees when sidecar data is ready.
- Get explicit
requires_reindex, stale-state, and noise guidance instead of silent bad context. - Install the MCP server and first-party workflow skill with one command.
- Avoid resident MCP startup through
npx; clients launch an installer-owned Node launcher.
Packages
| Package | Purpose |
|---|---|
@zokizuan/satori-core | Indexing, AST chunking, embeddings, Milvus/Zilliz storage, retrieval, incremental sync |
@zokizuan/satori-mcp | MCP server with the six agent-facing tools and lifecycle gates |
@zokizuan/satori-cli | Installer, doctor command, and shell access to MCP tools |
Quick Start
Install managed MCP config for every supported local client:
npx -y @zokizuan/satori-cli@0.4.2 install --client all
npx -y @zokizuan/satori-cli@0.4.2 doctor
Supported installers: codex, claude, opencode, and all.
The installer writes Satori-managed config and copies the first-party workflow skill:
satori
It also installs the MCP server once under ~/.satori/mcp-runtime/, writes a stable launcher at ~/.satori/bin/satori-mcp.js, and points client config at that launcher with Node. Resident MCP startup should not perform package-manager resolution.
Treat ~/.satori/ paths as installer-owned. Do not hand-write npx @zokizuan/satori-mcp into resident MCP config unless you are intentionally accepting package-manager startup latency.
Restart the MCP client after changing config.
First Repo Workflow
- Run the CLI installer and
doctor. - Restart your MCP client.
- Index one absolute repository path.
- Search, outline, graph, and read exact spans before edits.
manage_index action="create" path="/absolute/path/to/repo"
search_codebase path="/absolute/path/to/repo" query="where is auth refresh handled"
file_outline path="/absolute/path/to/repo" file="src/auth.ts"
call_graph path="/absolute/path/to/repo" symbolRef={...} direction="both"
read_file path="/absolute/path/to/repo/src/auth.ts" start_line=1 end_line=160
If any tool returns requires_reindex, run the hinted manage_index action="reindex" call first, then retry the original tool call. Use manage_index action="sync" for ordinary file or ignore-rule convergence.
Runtime Setup
Satori needs an embedding provider and a Milvus-compatible vector store before indexing. MCP startup, tools list, and doctor do not require provider credentials; provider-backed tool calls report MISSING_PROVIDER_CONFIG when setup is incomplete.
Run npx -y @zokizuan/satori-cli@0.4.2 doctor after setting env values to check the local setup before indexing.
Installer config and runtime config are intentionally separate:
- The installer owns the launcher and MCP client wiring.
- Satori runtime settings come from environment variables at MCP startup.
- Supported client installs expose the Satori runtime variable names in native client config so the setup is visible and editable:
- Codex writes active
env_varsforwarding plus an optional commented[mcp_servers.satori.env]template in~/.codex/config.toml. - Claude Code writes per-server
mcpServers.satori.enventries in~/.claude.jsonusing${VAR:-}pass-through values. - OpenCode writes per-server
mcp.satori.environmententries in~/.config/opencode/opencode.jsonusing{env:VAR}pass-through values.
- Codex writes active
- If you prefer storing literal values in a client config, replace the generated pass-through value for that client. In Codex, uncomment or add this table outside the installer-managed launcher block so reinstalls keep your edits:
[mcp_servers.satori.env]
EMBEDDING_PROVIDER = "VoyageAI"
EMBEDDING_MODEL = "voyage-4-large"
EMBEDDING_OUTPUT_DIMENSION = "1024"
VOYAGEAI_API_KEY = "pa-..."
VOYAGEAI_RERANKER_MODEL = "rerank-2.5"
MILVUS_ADDRESS = "https://your-zilliz-endpoint"
MILVUS_TOKEN = "your-zilliz-token"
Claude example:
{
"mcpServers": {
"satori": {
"env": {
"VOYAGEAI_API_KEY": "pa-...",
"MILVUS_TOKEN": "your-zilliz-token"
}
}
}
}
OpenCode example:
{
"mcp": {
"satori": {
"environment": {
"VOYAGEAI_API_KEY": "pa-...",
"MILVUS_TOKEN": "your-zilliz-token"
}
}
}
}
Cloud quality start:
EMBEDDING_PROVIDER=VoyageAI
EMBEDDING_MODEL=voyage-4-large
EMBEDDING_OUTPUT_DIMENSION=1024
VOYAGEAI_API_KEY=your-api-key
VOYAGEAI_RERANKER_MODEL=rerank-2.5
MILVUS_ADDRESS=your-milvus-endpoint
MILVUS_TOKEN=your-milvus-token
Get VOYAGEAI_API_KEY from the Voyage AI dashboard API keys page. For Zilliz Cloud, use the cluster public endpoint as MILVUS_ADDRESS and the API key or cluster credential as MILVUS_TOKEN. Local unauthenticated Milvus usually uses MILVUS_ADDRESS=localhost:19530 and no token.
Local-first start:
EMBEDDING_PROVIDER=Ollama
EMBEDDING_MODEL=nomic-embed-text
OLLAMA_HOST=http://127.0.0.1:11434
MILVUS_ADDRESS=localhost:19530
Provider, model, dimension, vector store, and schema are part of the index fingerprint. If they change, Satori blocks search with requires_reindex until you rebuild the index.
Search Defaults
Default search behavior is developer-oriented:
scope="runtime"so docs/tests do not dominate first results.resultMode="grouped"andgroupBy="symbol"to reduce duplicate chunks.rankingMode="auto_changed_first"to prefer active work when safe.debug=falseunless you are inspecting ranking/filter behavior.
Six MCP Tools
| Tool | Use it for |
|---|---|
list_codebases | See indexed roots and their lifecycle buckets |
manage_index | Create, sync, reindex, inspect status, or explicitly clear indexes |
search_codebase | Runtime-first semantic search with operators, grouping, freshness, and navigation hints |
file_outline | Read sidecar symbol outlines and resolve exact symbols without guessing |
call_graph | Traverse bounded caller/callee context from a search-provided symbolRef |
read_file | Read bounded files, ranges, annotations, or exact symbol spans |
What Satori Is Not
- Not an agent framework.
- Not a source-code write server.
- Not a replacement for tests, typecheck, code review, or grep.
- Not a promise that static call graph hints prove runtime or assertion coverage.
Satori gives the agent better evidence. It does not remove engineering judgment.
Repository Layout
packages/core indexing, retrieval, embeddings, vector store, sync
packages/mcp MCP server, tool schemas, lifecycle gates, generated tool docs
packages/cli managed installer, doctor, direct shell tool calls
docs/ behavior specs, feature inventory, architecture notes
satori-landing/ static website HTML source
Development
pnpm install
pnpm build
pnpm run versions:check
pnpm -C packages/mcp docs:check
pnpm -C packages/mcp manifest:check
pnpm --filter @zokizuan/satori-mcp test
pnpm --filter @zokizuan/satori-cli test
pnpm test:integration
Release Commands
Current release versions:
@zokizuan/satori-core@1.6.2@zokizuan/satori-mcp@4.11.2@zokizuan/satori-cli@0.4.2
Preflight before publishing:
pnpm install --frozen-lockfile
pnpm run versions:check
pnpm build
pnpm -C packages/mcp docs:check
pnpm -C packages/mcp manifest:check
pnpm --filter @zokizuan/satori-mcp test
pnpm --filter @zokizuan/satori-cli test
pnpm run release:smoke:mcp
pnpm run release:smoke:cli
Recommended public release path:
git tag v0.5.1
git push origin v0.5.1
The GitHub Actions release uses npm provenance and requires the NPM_TOKEN secret. Use the manual fallback only when you intentionally want to publish from a local authenticated shell without CI provenance:
pnpm run release:login
pnpm run release:all
pnpm run release:verify
Release Proof
The tag release workflow runs generated-doc checks, manifest checks, MCP tarball smoke tests, and CLI tarball smoke tests before publishing. The CLI installer tests also smoke install --client all against Codex, Claude, and OpenCode config in a temp home, asserting that resident client config launches the installer-owned Node launcher without npx, runtime cache paths, or custom startup timeout fields.
Release publishes use npm provenance from GitHub Actions. After publish, inspect registry integrity metadata with:
npm view @zokizuan/satori-core@<version> dist.integrity dist.shasum
npm view @zokizuan/satori-mcp@<version> dist.integrity dist.shasum
npm view @zokizuan/satori-cli@<version> dist.integrity dist.shasum
More Docs
- Architecture
- End-to-end behavior spec
- Features and use cases
- Public launch checklist
- Contributing
- Security policy
- Code of conduct
- MCP package README
Open Source
Satori is open source under the MIT License. The public MCP surface is intentionally read-only and fixed to six tools, so users can inspect behavior, self-host the index runtime, and contribute without expanding the agent write surface.
License
Satori is released under the MIT License.