Related Pages

Related topics: MCP Tools and API Client, Project Setup, Initialization, and Deployment

Project Overview and Architecture

Purpose and Scope

contextforge-mcp is the open-source Model Context Protocol (MCP) client for ContextForge. It provides persistent, long-term memory for AI coding agents by bridging local AI tools (Claude Code, Cursor, GitHub Copilot, ChatGPT, Windsurf) with the ContextForge memory backend over the standardized MCP wire protocol. The initial public release is tagged v0.1.76. Source: README.md:1-15

The client is delivered as a single, installable npm package and is intended to be invoked by an MCP-compatible host (an AI IDE or CLI). Once registered, it exposes a small, typed set of tools and resources that the agent can call to read, write, search, and subscribe to memory entries stored remotely in ContextForge. Source: package.json:1-30

High-Level Architecture

The repository follows a minimal, single-package layout: a TypeScript entry point, a thin type definition module, and a standard build configuration. Communication is unidirectional from the host to the client, then outward from the client to the ContextForge backend over HTTP/JSON-RPC.

flowchart LR
    Host["AI Tool / Agent<br/>(Claude Code, Cursor, Copilot,<br/>ChatGPT, Windsurf)"] -->|MCP stdio / JSON-RPC| Client["contextforge-mcp<br/>(src/index.ts)"]
    Client -->|HTTPS REST| Backend["ContextForge Memory Backend"]
    Backend -->|Persisted memory| Client
    Client -->|Tool / Resource results| Host

The entry point in src/index.ts registers the MCP server, declares the available tools, and forwards each tool invocation to the corresponding ContextForge REST endpoint. Type contracts shared between the client and backend are centralized in src/types.ts to keep request and response shapes consistent. Source: src/index.ts:1-20, src/types.ts:1-15

Core Components

Entry Point (`src/index.ts`)

The entry point wires up the MCP server, defines tool schemas, and implements request handlers. It is the only module that performs I/O, keeping side effects localized and the rest of the codebase pure. Tool handlers validate input against the schemas declared in src/types.ts before dispatching to the backend client. Source: src/index.ts:20-60

Type System (`src/types.ts`)

All shared structures — memory entries, search queries, tool input/output payloads, and MCP request envelopes — live in src/types.ts. Centralizing types prevents drift between the MCP-facing surface and the REST-facing surface and enables strict compile-time validation. Source: src/types.ts:1-40

Configuration & Build (`tsconfig.json`, `package.json`)

The project is written in TypeScript with strict enabled and compiled to ES2022, targeting Node.js 18+. The package.json declares the bin entry used by npx, declares the MCP and ContextForge dependencies as peers/runtime dependencies, and pins the executable contract used by hosts. Source: tsconfig.json:1-20, package.json:1-40

Data Flow

1. The AI host loads the client via npx contextforge-mcp and opens an MCP session over stdio.
2. The host enumerates tools and resources exposed by src/index.ts.
3. When the agent invokes a tool, the client parses the JSON-RPC payload, validates it against src/types.ts, and translates it into a REST request to ContextForge.
4. The backend returns a typed memory record; the client wraps it as an MCP CallToolResult and returns it to the host.
5. Errors from the backend are mapped to MCP error codes so the host can surface them to the agent. Source: src/index.ts:60-120, src/types.ts:15-45

Design Constraints and Conventions

• Single-package distribution. The client is a thin transport adapter; no local persistence is performed. Source: package.json:1-30
• Type-first contracts. Tool inputs and outputs are declared in src/types.ts and never constructed ad hoc. Source: src/types.ts:1-40
• Strict TypeScript build. The compiler enforces strict null checks and consistent module resolution. Source: tsconfig.json:5-18
• Host-agnostic. Because the surface is standard MCP, any MCP-compatible tool — including the five listed in the README — works without custom integration. Source: README.md:10-20

Summary

contextforge-mcp is a small, well-scoped TypeScript application: an MCP server (src/index.ts) backed by a centralized type module (src/types.ts), packaged as an npm CLI (package.json) and compiled under strict settings (tsconfig.json). Its architecture deliberately separates protocol concerns (MCP, owned by the entry point) from data contracts (owned by the types module) and from transport concerns (REST, delegated to the ContextForge backend), yielding a client that is easy to audit, extend, and integrate with any MCP-compatible AI coding agent. Source: README.md:1-25, src/index.ts:1-120, src/types.ts:1-45, package.json:1-40, tsconfig.json:1-20

Related Pages

Related topics: Project Overview and Architecture, Session Presence and Update Checker

MCP Tools and API Client

The ContextForge MCP client exposes a set of MCP (Model Context Protocol) tools that an AI agent can invoke to persist, retrieve, and manage long-term memory. The API client is the underlying HTTP transport responsible for talking to the ContextForge backend; the MCP tools are the user-facing tool definitions registered with the agent runtime (Claude Code, Cursor, GitHub Copilot, Windsurf, etc.).

Architecture Overview

The client follows a thin two-layer design: an MCP-facing tool layer registered with the agent runtime, and an HTTP-facing API client that translates tool calls into REST requests.

flowchart LR
    A[AI Agent Runtime] -->|JSON-RPC over stdio| B[MCP Server\nsrc/index.ts]
    B --> C[Tool Definitions\nsrc/types.ts]
    B --> D[API Client\nsrc/api-client.ts]
    D -->|HTTPS| E[ContextForge Backend]
    E -->|Response| D
    D --> B
    B --> A

• src/index.ts boots the MCP server and registers each tool handler. Source: src/index.ts:1-40
• src/types.ts defines the tool name, input schema, and response shapes exposed to the agent. Source: src/types.ts:1-60
• src/api-client.ts wraps fetch and provides typed request methods per endpoint. Source: src/api-client.ts:1-120
• src/task-params.ts centralizes query/body parameter construction for the tools. Source: src/task-params.ts:1-80
• src/config.ts supplies the base URL and authentication token to the API client. Source: src/config.ts:1-50

MCP Tool Surface

Each tool is declared with a stable name and a JSON Schema describing its inputs. The agent sees a flat list of tools; routing happens inside src/index.ts based on tool.name.

Common tool families exposed by the client include:

Tool schemas use standard JSON Schema types (string, integer, array, object) and rely on a projectId or namespace field for multi-tenant isolation. Source: src/types.ts:20-90

API Client Responsibilities

src/api-client.ts encapsulates every outbound HTTP call. Key responsibilities:

• Read base URL and auth token from src/config.ts. Source: src/api-client.ts:5-15
• Build request URLs by joining the base URL with a path constant. Source: src/api-client.ts:30-60
• Attach Authorization: Bearer <token> header when credentials are present. Source: src/api-client.ts:45-55
• Parse JSON responses and normalize errors into a typed ApiError. Source: src/api-client.ts:70-110
• Surface network failures (timeouts, non-2xx responses) as structured errors so MCP tools can return meaningful messages. Source: src/api-client.ts:100-130

The client is deliberately stateless; there is no in-memory cache, so each tool invocation triggers a fresh request. This keeps behavior predictable when multiple agent processes run concurrently against the same ContextForge workspace.

Request Lifecycle

For a representative tool such as memory_search, the lifecycle is:

1. The agent emits an MCP tools/call request over stdio.
2. src/index.ts looks up the handler for the requested tool name. Source: src/index.ts:25-35
3. The handler validates the inputs against the schema in src/types.ts. Source: src/types.ts:55-75
4. src/task-params.ts converts the validated inputs into URL query / body parameters. Source: src/task-params.ts:10-40
5. src/api-client.ts issues the HTTP request and awaits the response.
6. The handler returns an MCP ToolResult with the structured payload.

Configuration and Authentication

Configuration is read once at startup from environment variables (or a .env file processed by the MCP host):

• CONTEXTFORGE_API_URL — base URL of the ContextForge backend.
• CONTEXTFORGE_API_KEY — bearer token used for all requests.

src/config.ts exports a typed Config object so every consumer can import the same values. Source: src/config.ts:10-30 When the API key is missing the client surfaces a clear error rather than silently failing. Source: src/api-client.ts:15-25

Error Handling

Errors flow through three layers:

• Network / HTTP errors are caught in api-client.ts and converted to ApiError with status, code, and message. Source: src/api-client.ts:80-120
• Schema validation errors in src/index.ts reject the tool call before any network request. Source: src/index.ts:40-60
• Backend-reported errors (e.g. quota exceeded, missing project) propagate as MCP ToolResult with isError: true, allowing the agent to recover gracefully.

Extending the Client

To add a new tool:

1. Declare the schema in src/types.ts (name, description, input shape).
2. Add a matching request builder in src/task-params.ts.
3. Add a typed method to src/api-client.ts if a new endpoint is needed.
4. Register the handler in src/index.ts dispatching on tool.name.

Keeping tool definitions, transport logic, and parameter shaping in separate files means a contributor can add capabilities without touching unrelated code.

Related Pages

Related topics: Project Overview and Architecture, Session Presence and Update Checker

Project Setup, Initialization, and Deployment

contextforge-mcp is the open-source MCP (Model Context Protocol) client for ContextForge, providing persistent memory for AI coding agents such as Claude Code, Cursor, GitHub Copilot, ChatGPT, and Windsurf. This page documents how the project is configured, how initialization flows at runtime, and how it is packaged and deployed as a standalone MCP server. Source: README.md:1-40

Repository Layout and Configuration

The repository follows a TypeScript-first layout with two top-level entry scripts — src/init.ts and src/setup.ts — that act as the runtime hooks exposed to MCP hosts. The package.json declares the project metadata, dependencies, and the binary names registered for npx invocation. Source: package.json:1-60

Key configuration surfaces in the repository:

The clear separation between init.ts (per-launch bootstrap) and setup.ts (install-time registration) reflects the dual lifecycle of an MCP client: the server is *set up* once against a host tool, then *initialized* every time that host starts a session.

Initialization Lifecycle

When an MCP-compatible host (Claude Code, Cursor, Copilot, Windsurf, etc.) starts the ContextForge client, it executes the binary declared in package.json, which routes to src/init.ts. This module is responsible for bringing the client process into a state where it can speak the Model Context Protocol over the configured transport. Source: src/init.ts:1-40

The initialization responsibilities include:

• Resolving the ContextForge backend endpoint and authentication material from the environment or local configuration.
• Establishing the MCP transport (typically stdio for local hosts).
• Registering the tools and resources the client exposes to the host, as enumerated in server.json. Source: server.json:1-40
• Entering the MCP request/response loop and remaining alive until the host terminates the process.

Because the client is a thin protocol adapter rather than a long-running daemon of its own, initialization is expected to be lightweight and to fail fast if configuration is missing or invalid. Source: src/init.ts:1-40

Setup and Host Registration

src/setup.ts implements the installation flow described in the README. It is intended to be run interactively (for example via npx) to wire the client into a specific AI tool's MCP configuration so that subsequent launches are automatic. Source: src/setup.ts:1-40

The setup flow typically performs:

1. Target detection — identifying which host (Claude Code, Cursor, Copilot, ChatGPT, Windsurf) the user wants to integrate with, as documented in the README's supported-tools list. Source: README.md:20-80
2. Config mutation — writing the appropriate MCP server entry into the host's configuration file or registry, referencing the binary name declared in package.json. Source: package.json:1-60
3. Capability advertisement — copying or referencing the metadata in server.json so the host knows which tools the ContextForge client provides. Source: server.json:1-40

This split keeps setup.ts idempotent and host-specific while leaving init.ts host-agnostic, which is the conventional pattern for MCP clients.

Deployment via Container

For environments where installing the npm package is inconvenient — CI runners, sandboxed agents, or hosted deployments — the repository ships a Dockerfile that packages the client and its dependencies into a single image. Source: Dockerfile:1-40

flowchart LR
    A[Host AI Tool] -->|npx or registered binary| B[init.ts]
    B -->|stdio MCP transport| C[ContextForge Backend]
    A -->|one-time install| D[setup.ts]
    D -->|writes MCP config| A
    E[Dockerfile] -->|container image| B

When run from the container, the same init.ts entry point is invoked, so behavior is identical to a local npx install. Operators only need to supply the ContextForge backend credentials through environment variables at container start. Source: Dockerfile:1-40

Practical Workflow

A typical user flow, as described in the README, is:

1. Run npx contextforge-mcp setup (or the equivalent command exposed via package.json binaries) to register the client with the chosen AI tool. Source: package.json:1-60, Source: README.md:1-80
2. Restart the host tool so it picks up the new MCP server entry.
3. The host spawns the init binary on demand; from the user's perspective the persistent memory layer is now available inside their editor or chat client. Source: src/init.ts:1-40

This bounded setup — install via npm or container, register via setup.ts, launch via init.ts — is the entire deployment surface of the project in its v0.1.76 release.

Related Pages

Related topics: MCP Tools and API Client, Project Setup, Initialization, and Deployment

Session Presence and Update Checker

The contextforge-mcp client is composed of several small, single-purpose modules. Two of the most cross-cutting concerns — keeping a running session "alive" on the ContextForge backend and warning the user when a newer version of the client is published — are isolated into src/session-presence.ts and src/update-checker.ts. Both are wired into the client entrypoint in src/index.ts, making the runtime behavior of every installed instance uniform regardless of which AI tool (Claude Code, Cursor, GitHub Copilot, ChatGPT, Windsurf) drives it.

This page documents the role, internal mechanics, and integration points of those two modules.

Purpose and Scope

The two modules exist for different reasons but follow the same design philosophy: each runs as a passive background helper that does not block startup of the MCP server, and each fails silently rather than throwing into the agent's tool loop.

Both are listed in package.json as part of the main entrypoint ("main": "dist/index.js"), so any process that loads the client implicitly loads both helpers. Source: package.json:1-80

Session Presence Module

src/session-presence.ts is responsible for letting the ContextForge memory backend know that a particular agent session is still alive. Persistent memory only matters if the server can distinguish "the user is still here" from "the user closed their editor"; the presence module is the heartbeat that resolves that ambiguity.

Responsibilities

• Announce the session on startup with a stable client identifier and the active tool/host name.
• Emit periodic heartbeat pings so the backend does not garbage-collect the session.
• Tear down cleanly on process exit so the server can release the slot immediately.

Lifecycle

The module is instantiated once during client startup from src/index.ts, where it is constructed alongside the MCP server and any transport adapters. Source: src/index.ts:1-120

A typical lifecycle looks like:

flowchart LR
    A[index.ts boot] --> B[start session]
    B --> C[register on backend]
    C --> D{heartbeat timer}
    D -->|tick| E[ping backend]
    E --> D
    D -->|process exit| F[stop session]
    F --> G[backend frees slot]

Internally the module exposes start, stop, and heartbeat operations. The heartbeat interval is configurable so deployments behind long-running agents do not flood the backend with pings, while short-lived scripts still get a final stop call when the Node process exits. Source: src/session-presence.ts:1-120

Because failures are non-fatal, the module swallows network errors and only emits a console.warn line, allowing the rest of the MCP server to keep responding to tool calls even if the backend is temporarily unreachable. Source: src/session-presence.ts:40-90

Update Checker Module

src/update-checker.ts exists so users do not stay stuck on an outdated build with stale memory schema support. After the client has finished wiring up the MCP server and presence heartbeat, it spawns the update checker as a detached, one-shot background job.

What it does

• Reads the currently installed version from package.json.
• Queries the npm registry (or the equivalent GitHub releases endpoint) for the latest published contextforge-mcp version.
• Compares the two using semver semantics.
• If the local version is lower, prints a non-blocking notice pointing the user at the install command shown in the README (npx ...).

Why it is backgrounded

Running the check inline during boot would add network latency to every MCP startup, including ones launched from short-lived shells. By detaching it, the user gets the upgrade hint without paying for it on the critical path. The check is also guarded by an UPDATE_CHECK_DISABLED style escape hatch so CI and tests can opt out. Source: src/update-checker.ts:1-80

The module never modifies the running process. Its sole output is a console.log line, and it returns immediately whether or not the registry responded. Source: src/update-checker.ts:20-60

Integration in `src/index.ts`

Both helpers are initialized after the MCP Server instance is created and before transport adapters attach, ensuring that presence is announced the moment the server is reachable and that the update hint appears in the same console pane the agent and user are already watching. Source: src/index.ts:40-110

Operationally, a user invoking the client sees three things in their terminal during boot:

1. The MCP server's transport banner (stdio / SSE).
2. A single heartbeat line from session-presence.ts confirming the session is registered.
3. A version notice from update-checker.ts only when an upgrade is available.

If any of the three fail, the client still serves MCP tools — that resilience is the explicit goal of the architecture. Source: README.md:1-120

Configuration Surface

Both modules read from environment variables rather than command-line flags, which keeps the surface compatible with the npx contextforge-mcp invocation pattern recommended in the README. The most relevant knobs are:

• CONTEXTFORGE_API_URL — overrides the backend endpoint used by session-presence.ts for heartbeat pings.
• CONTEXTFORGE_DISABLE_UPDATE_CHECK — disables update-checker.ts entirely, useful for CI and air-gapped installs.
• CONTEXTFORGE_HEARTBEAT_INTERVAL_MS — tunes how often presence pings are emitted.

Source: src/session-presence.ts:10-40, Source: src/update-checker.ts:10-30

Summary

session-presence.ts and update-checker.ts are small, isolated background helpers that keep the ContextForge MCP client healthy and current without ever blocking the agent's tool loop. Session presence ensures the backend treats the running process as a live session; the update checker ensures users are gently nudged onto newer versions. Together they embody the client's design rule: never let auxiliary concerns break the MCP transport. Source: src/index.ts:1-120

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/alfredoizdev/contextforge-mcp

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/alfredoizdev/contextforge-mcp

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/alfredoizdev/contextforge-mcp

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/alfredoizdev/contextforge-mcp

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/alfredoizdev/contextforge-mcp

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/alfredoizdev/contextforge-mcp

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/alfredoizdev/contextforge-mcp

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using contextforge-mcp with real data or production workflows.

• v0.1.76 — Initial open-source release - github / github_release
• Configuration risk requires verification - GitHub / issue