ContextForge
ContextForge/DevSpan is a local MCP server for storing, linking, searching, and composing durable engineering context across repositories.
Create and manage Components, Repos, Tasks, and Governance entities.
Store/read/append/delete markdown subtopics for entities, with markdown on disk as source of truth.
Resolve fuzzy names and manage globally unique aliases.
Link context refs into tasks and assemble task packs, including governance cascade and FTS-based subtopic narrowing.
Suggest task links by traversing component
usesdependencies and scoring candidates.Attach/detach governance rules to components, repos, and tasks.
Add/remove external refs like Jira/GitHub/Linear pointers without fetching them.
Import externally fetched snapshots, track source URLs/timestamps, refresh pointers, and list stale sources.
Full-text search across stored subtopics.
Configure always-included refs and bind workspace paths to repos.
Rebuild the SQLite/FTS index from markdown and inspect recent logs.
Operate only locally over stdio; it does not fetch URLs or take credentials.
Allows importing and storing snapshots of Confluence pages with source tracking, and referencing Confluence pages from tasks as external refs.
Allows associating tasks with GitHub issues and pull requests by storing external references (e.g., 'pr/456'), enabling context about tracking systems without direct API access.
Allows associating tasks with GitLab issues/merge requests by storing external references, enabling context about tracking systems without direct API access.
Allows associating tasks with Jira issues by storing external references (e.g., ticket IDs and URLs), enabling context about tracking systems without direct API access.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ContextForge Compose task pack for 'fix-login-redirect' with component:api-gateway"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 ausesdependency 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_refsto 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.mdRepos:
overview.md,style.md,testing.md,local-dev.mdTasks:
goal.md,plan.md,notes.mdGovernance:
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 serverTests (pytest is a dev dependency):
uv sync
uv run pytestBehind an SSL-inspecting proxy? If
uv syncfails withinvalid peer certificate: UnknownIssuer, add--system-certsto theuvcommands (orexport 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), orDEVSPAN_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_contentstores text the caller already has.refresh_sourcereturns the stored URL so the caller can fetch it elsewhere.It does not take a credential.
delete_entityremoves an entity, its documents, and the links that pointed at it.
How to report a vulnerability is in SECURITY.md.
Requirements
Python 3.11+
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 markdowncontext://{type}/{slug}/{subtopic}— single subtopicpack://task/{slug}— assembled task pack (separate scheme avoids colliding withtask/{slug}/{subtopic})
Smoke test
After wiring it into Cursor, ask the agent to run these (or call them from the MCP panel):
create_component(slug="api-gateway", kind="system", description="Our edge proxy")upsert_context(ref="component:api-gateway/auth", content="OAuth2 with PKCE; tokens rotate hourly.")create_governance(slug="security-policy", description="Company-wide security baseline")add_governance(ref="component:api-gateway", governance_ref="governance:security-policy")create_task(slug="demo-task", description="Kicking the tires")link_task(task_slug="demo-task", refs=["component:api-gateway/auth"])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 toolsadd_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
link_taskB
Wire refs (component/repo/governance, optionally with subtopic) into a task.
Subtopic-level refs keep packs focused. Governance refs attached here also cascade to the assembled pack; governance attached to linked components/repos cascades automatically too.
Inputs: refs (required), task_slug (required). 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
searchC
Full-text search (SQLite FTS5) across all subtopic content.
Inputs: query (required), limit, entity_type. Returns: result
suggest_task_linksA
Propose candidate refs to link into a task.
Walks the uses graph from the anchors (or existing links if anchors
is None), collects components within depth hops, FTS-scores each
candidate's subtopics against the task's description + notes, and
returns top-K suggestions that aren't already linked.
Inputs: task_slug (required), depth, top_k, anchors. 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
unlink_taskB
Remove refs from a task's link list. Idempotent.
Inputs: refs (required), task_slug (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
Scored across 36 tools
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.
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.
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.
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
Related MCP Connectors
Repository knowledge graph MCP server for codebase understanding and debugging.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Guarded MCP server for agent-readable business truth, provenance, readiness, and discovery.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA server implementation of the Model Context Protocol (MCP) that provides REST API endpoints for managing and interacting with MCP resources.-
- AlicenseNot gradedqualityBmaintenancePrivate, local-first code intelligence MCP server that builds a static graph of repositories and exposes search, architecture, impact analysis, and review tools via MCP.MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that provides local software-system context compilation, exposing indexed code intelligence, dependency resolution, and cross-layer knowledge through the Knowledge API.-
- AlicenseNot gradedqualityCmaintenanceMCP 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 npmMIT