Skip to main content
Glama

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.

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.

Related MCP server: graphward

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).

The install procedure is install/README.md. Host files come from platforms.yaml next to nexus.md. With no environment file, user-global host config is left alone. Each enabled host gets this server block:

command: uv
args: ["run", "--directory", "/path/to/dev-span", "devspan"]

The store is ~/.devspan/ (override DEVSPAN_HOME), one store for every repo. Other repos do not need this checkout added to them.

To run the server by hand:

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.

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.

Available Tools

36 tools
add_aliasA

Add a short nickname for an entity. Globally unique.

Example: add_alias("component:api-gateway", "gw") — then resolve_ref("gw") returns the component.

Inputs: ref (required), alias (required). Returns: object

add_always_includeA

Add a ref to the always_include list.

Any ref in this list is automatically included in every task pack. Typical use: a personal-prefs governance entity you want everywhere.

Inputs: ref (required). Returns: result

add_external_refA

Attach a reference to an external tracking system (Jira, GitHub, etc.).

ContextForge does not fetch these — it just stores pointers. Use a separate MCP server (Atlassian, GitHub, etc.) to retrieve current state.

Inputs: id (required), system (required), task_slug (required), url. Returns: result

add_governanceA

Attach a governance ref to a component/repo/task.

The governance content will be included in any task pack that touches this entity (directly via link_task, or via parent-component cascade for repos). Cannot attach governance to another governance entity.

Inputs: ref (required), governance_ref (required). Returns: object

append_contextB

Append content to a subtopic, creating it if missing.

Separates appended content from existing with a blank line.

Inputs: ref (required), content (required). Returns: object

bind_workspaceA

Associate a local workspace path with a repo slug.

Once bound, get_current_workspace(path) returns the repo slug so the LLM can auto-select relevant context when you're working in that dir.

The MCP client's Roots capability is the canonical source of the current workspace path; this tool expects that path passed in.

Inputs: path (required), repo_slug (required). Returns: object

create_componentA

Create a new Component entity.

A Component is any coherent unit of functionality that you hold context about: an internal subsystem, an external service, an API, a database, a library, or a tool. The kind tag lets you filter later.

Inputs: slug (required), kind, uses, aliases, +2 more. Returns: object

create_governanceA

Create a new Governance entity — a reusable guideline.

Governance entities hold cross-cutting rules that apply to multiple components/repos/tasks: security policies, API design standards, branding guidelines, user preferences. Any other entity can reference them via governance: [...] in its frontmatter or via add_governance.

When assembling a task pack, governance refs cascade: the task's own governance + governance attached to each linked component/repo + parent components of linked repos. All deduped.

Scaffolded subtopics: overview, rules.

Inputs: slug (required), aliases, description. Returns: object

create_repoA

Create a new Repo entity.

Repos hold long-lived facts about a codebase: style, testing, layout, local-dev setup, conventions. A repo optionally belongs to a parent Component (e.g. gateway-proxy-repo -> component:api-gateway).

Inputs: slug (required), aliases, component, governance, +1 more. Returns: object

create_taskB

Create a new Task entity.

Tasks are transient units of work (a feature, a bug, an investigation) that compose context by linking specific Component/Repo/Governance refs via link_task. Scaffolded subtopics: goal, plan, notes.

Inputs: slug (required), aliases, governance, description. Returns: object

delete_contextC

Delete a single subtopic. Parent entity is preserved.

Inputs: ref (required). Returns: object

delete_entityA

Delete an entity and ALL its subtopics. Destructive.

Also cleans up: aliases, task_links referencing this entity, governance links, uses-graph edges, and nullifies repo->component parent pointers.

Requires an entity-level ref (no subtopic).

Inputs: ref (required). Returns: object

get_configA

Return the current ContextForge config (always_include, workspaces).

Inputs: no named parameters. Returns: object

get_contextA

Read the current context for an entity or a single subtopic.

Accepts an entity ref ("component:api-gateway") or a subtopic ref ("component:api-gateway/auth"). For entity refs, returns the meta + all subtopics.

Inputs: ref (required). Returns: object

get_current_workspaceB

Resolve a workspace path to its bound repo (and parent component, if any).

Inputs: path (required). Returns: object

get_task_packA

Assemble the full context pack for a task.

Returns the task's own meta+subtopics, all resolved linked refs, and a deduplicated governance section. If include_always is True (default), refs from config.json always_include are merged in.

When focus is True (default), entity-level refs with more than per_entity_top_k subtopics are FTS-narrowed against the task's description + own notes — only the top-K most relevant subtopics are included; the rest are returned in dropped for on-demand pull via get_subtopic / get_context. Subtopic-level refs (component:foo/bar) bypass narrowing.

Inputs: task_slug (required), focus, min_score, include_always, +1 more. Returns: object

import_contentA

Store content fetched from an external source as a subtopic.

Use this after another MCP tool (e.g. an Atlassian MCP for Confluence) returns page content — ContextForge then owns it as a snapshot with source tracking. source_fetched_at is set to now automatically.

Inputs: ref (required), content (required), source_url (required), source_name. Returns: object

list_componentsB

List all Components, optionally filtered by kind.

Inputs: kind. Returns: result

list_governance_entitiesC

List all Governance entities.

Inputs: no named parameters. Returns: result

list_reposB

List all Repos.

Inputs: no named parameters. Returns: result

list_stale_sourcesC

List imported subtopics whose source_fetched_at is older than a cutoff.

Inputs: older_than_iso (required). Returns: result

list_tasksB

List all Tasks.

Inputs: no named parameters. Returns: result

refresh_sourceA

Return the source_url for a subtopic so the caller can re-fetch.

ContextForge does NOT fetch. The caller (LLM) uses another MCP tool or HTTP fetcher to retrieve fresh content, then calls import_content again with the same ref.

Inputs: ref (required). Returns: object

reindexA

Rebuild the SQLite + FTS5 index from markdown files on disk.

Use after manual edits on disk, or if the index seems stale. Filesystem is the source of truth.

Inputs: no named parameters. Returns: object

remove_aliasC

Remove an alias from an entity.

Inputs: ref (required), alias (required). Returns: object

remove_always_includeC

Remove a ref from the always_include list.

Inputs: ref (required). Returns: result

remove_external_refC

Detach an external reference from a task.

Inputs: id (required), system (required), task_slug (required). Returns: result

remove_governanceC

Detach a governance ref from an entity.

Inputs: ref (required), governance_ref (required). Returns: object

resolve_refA

Resolve a fuzzy query ("the gateway", "gw", "auth-gw") to candidate refs.

Checks exact slug, exact alias, and case-insensitive name substring. Returns ranked candidates [{ref, source, score}] — call this before writing if the user refers to something by nickname or description.

Inputs: query (required), type_filter. Returns: result

tail_logsA

Return the most recent lines from the persistent usage/debug log.

The log at ~/.contextforge/logs/contextforge.log (rotating) captures tool invocations, pack assemblies (with dropped counts, sizes, timings), entity creates, links, governance attachments, resolves, suggestions, context writes, and workspace binds. This is the primary signal for understanding real usage and tuning focus/governance behavior.

Inputs: n. Returns: result

unbind_workspaceB

Remove a workspace→repo binding.

Inputs: path (required). Returns: object

upsert_contextB

Create or overwrite a subtopic's full content.

Requires a subtopic ref. Parent entity must already exist. Clears any previously stored source_url/source_name when content is overwritten without source metadata.

Inputs: ref (required), content (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 36 tools

    Disambiguation4/5

    Pairings like append_context/upsert_context/import_content and get_context/get_task_pack are superficially similar, but their descriptions clearly delineate write mode (append vs. overwrite vs. imported snapshot) and read scope (single entity vs. assembled pack). The create_governance/add_governance and delete_context/delete_entity pairs are likewise disambiguated by entity-level vs. ref-level wording. No two tools appear to do the same thing.

    Naming Consistency5/5

    Every tool follows a lowercase snake_case verb-first pattern (append_context, list_repos, bind_workspace, unlink_task), and paired operations share prefixes (add_*/remove_*, create_*, list_*). 'search' and 'reindex' are bare verbs but still read as imperatives and don't clash with the pattern. This is a highly internally consistent naming scheme.

    Tool Count3/5

    36 tools is heavy, but the domain is genuinely broad: four entity types, subtopic writes, linking, aliases, external refs, workspace bindings, imports, config, search, and logging each get explicit surface area. Some thin pairs like add/remove_always_include and bind/unbind_workspace could be folded into a config/workspace update tool, and agents face a large decision space. The count is defensible but sits above the well-scoped band.

    Completeness4/5

    CRUD is nearly complete: create/list/delete for entities, full read/write/delete for subtopics, link/unlink, add/remove for aliases, refs, and governance, plus a coherent re-fetch workflow via refresh_source + import_content. Notable gaps are the absence of entity metadata updates (re-parenting a repo or editing a task's description requires delete+recreate) and no listing of aliases or external refs per entity. get_task_pack, search, and suggest_task_links cover the high-level workflows well.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A server implementation of the Model Context Protocol (MCP) that provides REST API endpoints for managing and interacting with MCP resources.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that provides coding agents with structured repository context, including graph-based navigation, dependency analysis, runtime flow tracing, and configuration surface across supported stacks.
      59 npm
      MIT