Allows coding agents to record, retrieve, and re-verify codebase explanations with exact source evidence and version history.
Also known as pontivus-com/span, span-mcp
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- 2,552
- Latest version
- 0.10.4
- Last commit
- Nov 16, 2026
- License
- Apache-2.0
What is Span MCP?
Span allows coding agents to record, retrieve, and re-verify codebase explanations with exact source evidence and version history.
Summary generated from the project's README
About Span MCP server
Coding agents that need to maintain continuity between development sessions can use Span to preserve their technical investigations. This local MCP server allows an agent to record complex explanations of a codebase, including the specific source evidence used to reach a conclusion and the version history of that understanding. By capturing why certain boundaries or logic flows exist, the server ensures that subsequent sessions can retrieve these insights and verify if the underlying code has changed.
Users interact with the server through three primary tools: ask, record, and reconsider. An agent uses ask to find current understandings or identify gaps, record to save a conclusion with its supporting files or domains, and reconsider to re-evaluate explanations when dependencies or source files are modified. The server runs locally via stdio on Linux systems using Python 3.12+ and does not require external model provider credentials, as the agent provides its own intelligence. It manages state outside of the target repositories to keep investigations reusable and traceable.
What you can do with it
- 1Preserving codebase investigationsAn agent can save a detailed explanation of a service boundary along with the specific files that support it.
- 2Verifying knowledge after code changesWhen source files are updated, an agent can trigger a reassessment to see if previous conclusions still hold true.
- 3Identifying knowledge gapsAn agent can query a specific part of the system to find out what is currently understood and what evidence is missing.
Written from the project's README. Every use case is checked against a quote from it.
How to install Span MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Span MCP in Claude Code
$ claude mcp add span -- uvx span-mcpInstall Span MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"span": {
"command": "uvx",
"args": [
"span-mcp"
]
}
}
}Install Span MCP in VS Code
.vscode/mcp.json
{
"servers": {
"span": {
"type": "stdio",
"command": "uvx",
"args": [
"span-mcp"
]
}
}
}Install Span MCP in VS Code CLI
$ code --add-mcp '{"name":"span","type":"stdio","command":"uvx","args":["span-mcp"]}'Install Span MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"span": {
"command": "uvx",
"args": [
"span-mcp"
]
}
}
}Install Span MCP in Codex
$ codex mcp add span -- uvx span-mcpInstall Span MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.span] command = "uvx" args = ["span-mcp"]
Install Span MCP in Gemini CLI
$ gemini mcp add -s user span uvx -- span-mcpInstall Span MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"span": {
"command": "uvx",
"args": [
"span-mcp"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablepontivus-com/span is public and reachablegithub.com/pontivus-com/span ↗Pass
- Package names this repository as its sourcespan-mcp names pontivus-com/span as sourcepypi.org/project/span-mcp/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for span-mcppypi.org/project/span-mcp/ ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/pontivus-com/span ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from span-mcpPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubKeep the understanding your agent worked for
A coding agent traces a request across services, checks the tests, finds the contract, and explains why the boundary exists. The next session should be able to find that explanation and see whether its support still holds.
Span makes that investigation reusable. It is a local MCP server where agents record coherent explanations with exact source support, explicit gaps, and version history. Later agents can discover the explanation through an ordinary engineering question, then inspect what is current, disputed, or changed.
The coding agent does the thinking. Span keeps the record and checks its support.
Three tools — ask, record, reconsider — carry one lifecycle: find
current understanding, retain a supported conclusion, and re-align after change.
How it works
- Investigate a real question. Ask about the surface you are looking at. Span returns current answers with surface status, or a gap with inspectable source evidence.
- Record the useful result. Save one conclusion at a time with the file it rests on, or declare a service/domain surface for a cross-file explanation. Work that started outside Span can be recorded directly; the flat create derives support from the locator you already read.
- Reuse in a fresh session. Ask the same question about the same surface, and retrieve the result with live support and challenges.
- Reassess after change. Check affected dependencies, investigate what changed, then confirm, correct, replace, or withdraw the explanation. Earlier versions remain inspectable.
One explanation can span code, tests, CSS, configuration, and contracts. The agent decides what is worth recording; a file inventory does not become a mandatory documentation campaign.
See the lifecycle
Illustrative tool sequence, not literal request JSON. The installed schemas and MCP reference own the wire grammar.
ask: "How does checkout decide whether to charge?"
→ Gap: exact evidence, a context, and an explicit question
agent investigates; record admits the source it just read
record(kind="understanding", conclusion, locator|observation_id|support)
→ committed receipt, understanding version 1, support qualification
fresh session asks the same question about the same surface
→ Answer with current conclusions, evidence, and surface status
ask(selector=UnderstandingSnapshotSelector)
→ recorded explanation, live support, gaps, and challenges
supporting source changes
reconsider(changed_paths)
→ every affected surface, with containment, direct, and indirect reasons,
and per-conclusion support state
agent investigates and records a correction against the expected version
→ version 2; version 1 remains history
A query names the surface; saved understanding is matched by that surface and the recorded question. Wording is not treated as semantic equivalence, and a returned conclusion is a starting point for judgment.
Know what can be reused
| Qualification | What the agent can conclude |
|---|---|
CURRENT |
The declared support still passes its checks. Applicability and semantic correctness still need judgment. |
REASSESSMENT_REQUIRED |
Source, authority, premise, or recorded membership support changed. Revisit the affected explanation. |
UNVERIFIABLE |
Required support cannot be established. The limitation stays explicit. |
Gaps and challenges remain visible independently of support currency. Matching bytes do not settle a dispute, and test existence does not establish a pass. Independent verification records the observations or evidence actually tested and preserves failures as failures.
Recording is atomic and returns a receipt. The caller preserves identity before sending; retrying the same identity and content recovers the retained receipt after a lost response or process restart. A committed receipt and a present support qualification answer different questions.
Quick start
The verified installation path is Linux with Python 3.12+, Node.js, and npm. From a checkout containing the current candidate:
python3 scripts/install-span.py --repo /path/to/your/repo
For a published package release, install span-mcp with your Python package
manager and run span-install --repo /path/to/your/repo. See
install and connect for registration, verification, and the
offline store transition.
The installer provisions the managed structural indexer, runtime, skills, and
host integration. With the default global OpenCode scope, it registers the
Span lifecycle plugin and MCP server in the same global OpenCode configuration.
Repeat installs use the receipt's absolute MCP path unless
--opencode-config explicitly relocates it.
Reconnect your coding agent after upgrade so it receives the new tools and
instructions. Verify operational setup with:
span-install --verify-only
Setup creates no understanding. Begin with a question from your actual task; see using Span.
Beta host status
| Host | Current scope |
|---|---|
| Codex | Supported; three-tool delivery captured with hooks disabled. The flat-create re-capture is pending (account quota). |
| OpenCode | Supported; three-tool and flat-create delivery captured. The installer plugin puts the first ask before the first source read in 5/5 measured runs. |
| Claude Code | Supported managed host; registration/health and installer behavior are covered. Authenticated model-delivery grammar and caller identity remain UNVERIFIED. |
| Other MCP hosts | Manual stdio connection is available; model-delivery behavior needs host-specific verification. |
Registration, hook configuration, and model-delivered behavior are distinct. Optional hooks provide notices; retrieval and recording still check support when hooks are absent. See host integration.
Fits around your agent
Span runs locally over stdio and keeps state outside target repositories. Your agent uses its own model, tools, edits, and test runner. Span does not invoke a model or store provider credentials. Structural search helps investigation; recorded conclusions retain the agent's interpretation and declared support.
The intended benefit is continuity between sessions and a focused review of changed support. Recording and host delivery have costs. Measured cost is class-specific: repeated reuse of a covered surface breaks even at two uses on the tested tasks, while single-use implementation is currently more expensive than reading. This beta makes no universal time/token-saving claim or completed comparative product-fitness ACCEPT claim. See acceptance.
Status and documentation
This checkout describes 0.10.0: three lifecycle tools (ask, record,
reconsider), schema-11 storage, surface-scoped answers, explicit store
transition, and live support qualification. 0.10.0 makes the compact record
grammar the only recording grammar: create takes exactly one evidence mode,
updates are compact semantic deltas, new conclusion lineage identities are
derived by Span, and expected_version remains compare-and-set. reconsider
returns the expected version and context needed for the next record, and the
legacy parallel create/challenge/verification wire path is removed.
Host delivery is captured for the valid compact lifecycle on OpenCode; Codex
has a current-candidate smoke create capture, and its full compact update
journey is not re-observed. Claude registration/health and installer behavior
are covered, while its authenticated model-delivery grammar and caller identity
remain UNVERIFIED. OpenCode removes an unknown old-form field before
delivery, so strict unknown-field rejection is not established through that
host. Comparative fitness remains class-scoped (FD-53, FG-7). macOS and Windows
installation paths remain unverified. Publication and product acceptance are
separate from the implementation version.
- Install and connect
- Using Span and first investigation
- Agent lifecycle and MCP reference
- Support and reassessment
- Evidence and authority
- Scope and boundaries and FAQ
- Architecture, repository overview, and all docs
- Changelog
Older acceptance evidence retains its historical protocol and does not certify the rebuilt API or comparative value.
Contributing
See contributing. Preserve the central contract: useful understanding stays attached to its support, noncurrent or uncertain state stays explicit, and corrections preserve history. Security reports go through SECURITY.md; support expectations are in SUPPORT.md.
Registry
Official MCP Registry entry: io.github.pontivus-com/span
mcp-name: io.github.pontivus-com/span
License
Span is licensed under Apache License 2.0 (Apache-2.0). See LICENSE.
Span MCP questions
How do I add Span MCP to Claude Code?
Run claude mcp add span -- uvx span-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Span MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What does Span do for a coding agent?
Span enables agents to record coherent explanations with exact source support, explicit gaps, and version history to make investigations reusable across sessions.
How does Span handle changes in the codebase?
The reconsider tool allows agents to check affected dependencies and investigate changes to confirm, correct, replace, or withdraw previous explanations.
Does Span require a model or cloud provider?
No, Span runs locally over stdio and does not invoke a model or store provider credentials; the agent uses its own model and tools.