DevSpan

DevSpan

DevSpan gives an AI client durable engineering context across repositories: components, repos, tasks, and governance, stored as markdown and composed per task.

Not a wiki, not standing guidance, and not a bulletin. It does not fetch external pages. An external ref is a pointer. A snapshot is stored only when the caller hands over the text.

Built for the cross-repo reality: a single task touches the UI repo, the API repo, the gateway, a service you do not own, and a database. Capture the reusable facts once and compose them for the task.

Lineage: evolved from the earlier file-based Cursor framework ai-context-framework (rules · packs · graph · slash commands). That repo is archived as the v1 path; this project is the active implementation.

Structure: DESIGN.md. What moved: CHANGELOG.md.

Model

• Component — a coherent unit of functionality. Kinds: system | service | api | database | library | tool. Can declare a uses dependency graph over other components.
• Repo — a codebase. Optionally belongs to a parent Component (e.g. gateway-proxy-repo → component:api-gateway).
• Task — a transient unit of work that composes context by linking specific Component/Repo/Governance refs. Can carry external_refs to Jira/GitLab/Confluence/etc.
• Governance — reusable cross-cutting guidelines (security policy, API design standards, user prefs, branding). Any other entity can reference them; they cascade into task packs automatically.

Ref grammar: type:slug (entity) or type:slug/subtopic (one document within an entity).

Examples: component:api-gateway, component:api-gateway/auth, repo:ui-repo/testing, task:fix-login-redirect, governance:security-policy/data-handling.

Storage

All data lives under ~/.devspan/ (override with DEVSPAN_HOME):

~/.devspan/
  components/{slug}/_meta.md, {subtopic}.md
  repos/{slug}/_meta.md, {subtopic}.md
  tasks/{slug}/_meta.md, {subtopic}.md
  governance/{slug}/_meta.md, {subtopic}.md
  .index/devspan.db       # SQLite + FTS5, rebuildable via `reindex`
  config.json                  # always_include refs + workspace bindings
  logs/devspan.log        # persistent usage + debug (rotating)

Markdown files are the source of truth. The SQLite index is derived — if it drifts, call reindex.

Storage opens one SQLite connection per thread (threading.local()) with PRAGMA journal_mode=WAL so FastMCP's worker threads can each call in safely. This is load-bearing — don't cache a Connection on the instance or remove the WAL pragma.

New entities get scaffolded subtopics:

• Components: overview.md, auth.md, integration.md, gotchas.md
• Repos: overview.md, style.md, testing.md, local-dev.md
• Tasks: goal.md, plan.md, notes.md
• Governance: overview.md, rules.md

Delete the ones you don't want.

Install & run

uv is the expected package manager (install via brew install uv or Astral's installer).

cd /path/to/dev-span
uv sync
uv run devspan            # stdio MCP server

Tests (pytest is a dev dependency):

uv sync
uv run pytest

Behind an SSL-inspecting proxy? If uv sync fails with invalid peer certificate: UnknownIssuer, add --system-certs to the uv commands (or export UV_SYSTEM_CERTS=1).

Logs go to stderr and to ~/.devspan/logs/devspan.log (rotating text file, on by default). The file is the durable record for usage analysis and trials.

Default level is INFO (pack assembly summaries, creates, links, governance, resolves, etc.). Set DEVSPAN_LOG_LEVEL=DEBUG for full FTS scoring breakdowns per entity — useful for tuning per_entity_top_k and min_score.

Use the tail_logs(n) tool to inspect recent activity from inside the MCP.

For development / dogfooding where you want the same events written to a second location (e.g. inside the source repo so logs travel with the checkout), set:

• DEVSPAN_DEV_LOG_DIR=/path/to/desired/dir (recommended), or
• DEVSPAN_LOG_FILE=/path/to/specific.log

You get both the normal home log and the extra location.

Wire into Cursor

Install it globally, not per-project. DevSpan is a single global store(~/.devspan/) meant to serve every repo you work in. The --directorybelow only tells uv where this server's code lives — the running server reads~/.devspan/ regardless of which workspace is open, so you never need to addthe dev-span folder to your other repos. Wire it once, globally, and it'savailable everywhere.

1. Register the MCP server globally

Add it to your global Cursor MCP config (~/.cursor/mcp.json, or yourmcp-manager proxy config if you use one), replacing the placeholder with thisrepo's path on your machine:

{
  "mcpServers": {
    "devspan": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/dev-span", "devspan"]
    }
  }
}

Behind an SSL-inspecting proxy, add "--system-certs" as the first entry in args,or set UV_SYSTEM_CERTS=1 on the server's env. Restart Cursor (or toggle theserver under Settings → MCP) and confirm the devspan tools appear.

A project-scoped .cursor/mcp.json is also committed in thisrepo, but it only activates when this repo is the open workspace — fine forhacking on DevSpan itself, not for using it across your work.

2. Make the router rule global too

The MCP registration gives the agent the tools; the.cursor/rules/devspan-router.mdc rulegives it the behavior (when to recall and capture context proactively). A rulethat lives only in this repo won't apply in your other repos — so it must be globalas well. Two equivalent options:

• Symlink the rule into your global Cursor rules location (single source oftruth — edits here propagate automatically). On Windows this needs Developer Modeor an elevated mklink.
• Copy the rule into your global Cursor rules location (more portable; re-copyafter edits).

Either way the rule is alwaysApply: true, so once it's global it's in context forevery session — that's what lets the agent use DevSpan without being told to.

Tools

The tools, what they take, and what they change are in docs/tools.md. Each tool sets readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. None of them are open to the network.

On initialize the server returns the operating note from the server code. This page does not repeat it.

Trust boundary

• Transport is stdio. The host starts a local process as the user who launched it.
• It reads and writes markdown under DEVSPAN_HOME (default ~/.devspan), plus a derived SQLite index in that same folder.
• It does not fetch URLs. import_content stores text the caller already has. refresh_source returns the stored URL so the caller can fetch it elsewhere.
• It does not take a credential.
• delete_entity removes an entity, its documents, and the links that pointed at it.

How to report a vulnerability is in SECURITY.md.

Requirements

• Python 3.11+
• uv
• FastMCP 2, over stdio

There is no published package. Clone the repository and run it from the checkout, as in Install and run above.

Resources

• context://component/{slug} / context://repo/{slug} / context://task/{slug} / context://governance/{slug} — full entity as markdown
• context://{type}/{slug}/{subtopic} — single subtopic
• pack://task/{slug} — assembled task pack (separate scheme avoids colliding with task/{slug}/{subtopic})

Smoke test

After wiring it into Cursor, ask the agent to run these (or call them from the MCP panel):

1. create_component(slug="api-gateway", kind="system", description="Our edge proxy")
2. upsert_context(ref="component:api-gateway/auth", content="OAuth2 with PKCE; tokens rotate hourly.")
3. create_governance(slug="security-policy", description="Company-wide security baseline")
4. add_governance(ref="component:api-gateway", governance_ref="governance:security-policy")
5. create_task(slug="demo-task", description="Kicking the tires")
6. link_task(task_slug="demo-task", refs=["component:api-gateway/auth"])
7. get_task_pack(task_slug="demo-task") — you should see the auth subtopic AND the security-policy content (cascaded through the governance link on the component).

License

MIT. Runtime deps are permissive (MIT/BSD/Apache-2.0) — no copyleft.