Span
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Keep 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 from the current surface view, 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 the
agent lifecycle: find
current understanding, retain a supported conclusion, and re-align after change.
Related MCP server: Estelle
How it works
Start from the surface. Ask for the current surface view with no question or request identity. Span returns current grouped understanding with status, or a gap with concrete source pointers. Select source bytes explicitly only when the investigation needs them.
Retain established understanding. 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 for the surface document view without a question, then select the applicable current conclusion.
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 retains supported conclusions as part of the investigation.
See the lifecycle
Illustrative tool sequence, not literal request JSON. The installed schemas and MCP reference own the wire grammar.
ask(surface)
→ current grouped Answer, or Gap with source pointers
agent selects needed source bytes explicitly when required
ask(surface, request_id, evidence)
→ same Answer/Gap classification plus evidence admission/context
agent investigates and records what it established
record(kind="understanding", conclusion, locator|observation_id|support)
→ compact acceptance with receipt selector, version, and live qualification
fresh session asks the surface
→ current document view grouped by recorded question
ask(selector=RecordedQuestionSelector)
→ exact known recorded-question membership
ask(selector=UnderstandingSnapshotSelector)
→ exact recorded explanation, live support, gaps, and challenges
supporting source changes
reconsider(changed_paths)
→ every affected surface, with containment, direct, and indirect reasons,
per-conclusion support state, and a re-establishment context
agent investigates and records a correction against the expected version
→ version 2; version 1 remains historyPure reuse names the surface and returns all current membership grouped by
recorded question. Exact targeted reuse uses RecordedQuestionSelector only
when that recorded question is already known. Wording is never treated as
semantic equivalence, and a returned conclusion remains a starting point for
judgment.
Know what can be reused
Qualification | What the agent can conclude |
| The declared support still passes its checks. Applicability and semantic correctness still need judgment. |
| Source, authority, premise, or recorded membership support changed. Revisit the affected explanation. |
| 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. Ordinary acceptance returns a receipt selector plus the accepted coordinates and live qualification; the immutable receipt remains in storage and is retrieved explicitly when exact replay/audit detail is needed. The caller preserves identity before sending, so retrying the same identity and content recovers the retained acceptance after a lost response or restart.
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/repoFor 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-onlySetup creates no understanding. Begin with the relevant surface from your actual task; see using Span.
Beta host status
The 0.10.5 repository/installable contract is verified through the built package and installed stdio MCP lane. Candidate-specific live model-host conversion was not rerun from this execution environment; earlier captures are historical and are not reused as 0.10.5 acceptance evidence.
Host | 0.10.5 candidate status |
Codex | Integration target retained; candidate-specific live model-delivery UNVERIFIED. |
OpenCode | Integration target and packaged notice delivery retained; candidate-specific live model-delivery UNVERIFIED. |
Claude Code | Managed registration/health support retained; authenticated model-delivery remains UNVERIFIED. |
Other MCP hosts | Manual stdio connection remains available; host-specific model-delivery is UNVERIFIED. |
Registration, hook configuration, and model-delivered behavior are distinct. Hooks provide lifecycle reminders; 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.5: evidence is retained as references and
hashes rather than stored source copies, and each repository can carry a
deployable Span artifact at .span/backups/ that loads and rebinds on a fresh
clone. The public operations remain ask, record, and reconsider; storage is
schema 12. See the changelog for verification and upgrade
instructions, and backup and recovery for the operator
policy.
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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Shared, scoped, reviewable team memory for AI coding agents.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Cache source-backed repository context so coding agents can reuse knowledge across sessions.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides AI coding agents with persistent architectural memory of codebases, enabling impact analysis, test generation, and code generation with reduced token usage.MIT
- AlicenseNot gradedqualityBmaintenanceProvides persistent memory for coding agents and grounds their claims by verifying against the actual codebase, preventing hallucinated responses.Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables agentic coding tools to maintain a living, in-repo model of intent, architecture, and code, with deterministic indexing, bidirectional linking, and continuous drift detection for task-scoped context and reconciliation.MIT
- AlicenseNot gradedqualityCmaintenanceProvides AI coding agents with fast, deterministic access to code graphs, knowledge lifecycle state, and cross-document symbol links, enabling compact context retrieval and seamless session handoffs.1MIT