context-first-mcp

v1.2.6

Published

2 months ago

Context Custodian MCP server — npx entry point for local stdio transport

Context-First MCP

Context-First MCP is a local stdio Model Context Protocol server for keeping long AI-agent conversations grounded, inspectable, and less prone to context drift.

This package is the end-user MCP package. Use it with npx from Claude Desktop, Cursor, Codex, VS Code, or any MCP client that supports stdio servers.

Which package should I use?

Use context-first-mcp when configuring an MCP client:

npx -y context-first-mcp@latest

The larger package, @xjtlumedia/context-first-mcp-server, is the core library. It contains the server implementation, tools, state engine, and analysis modules. You normally do not run it directly with npx.

In short:

| Package | Use it for | Contains | | --- | --- | --- | | context-first-mcp | MCP client configuration and npx startup | Small stdio launcher | | @xjtlumedia/context-first-mcp-server | Programmatic imports and internal implementation | Core server, tools, memory, reasoning, analysis |

Requirements

Node.js 18 or newer
An MCP client that can launch stdio servers
No API keys are required for the default local server

Quick start

Run the server directly:

npx -y context-first-mcp@latest

Most users should add it to an MCP client instead of running it manually.

MCP client configuration

Claude Desktop, Cursor, and similar JSON configs

{
  "mcpServers": {
    "context-first": {
      "command": "npx",
      "args": ["-y", "context-first-mcp@latest"]
    }
  }
}

Codex config.toml

[mcp_servers.context-first]
command = "npx"
args = ["-y", "context-first-mcp@latest"]

Restart your MCP client after changing the configuration.

What it provides

Context-First MCP exposes tool families for:

Context health checks and drift detection
Memory inspection, recall, curation, and compaction
Reasoning support and self-check workflows
Truthfulness and verification-oriented checks
Research workflow support
Sandboxed analysis helpers
MCP resources for the usage protocol and tool catalog

The server runs locally over stdio. It is designed to be used as supporting infrastructure for AI agents, not as a standalone web app.

Programmatic usage

If you are building your own transport or embedding the server in another Node.js process, import the core package directly:

import { createContextFirstServer } from "@xjtlumedia/context-first-mcp-server";

const { server, store } = createContextFirstServer({
  name: "my-context-first-server",
  version: "1.0.0",
});

Use this wrapper package only when you need the standard npx stdio entry point.

Troubleshooting

`Unsupported URL Type "workspace:"`

Upgrade to [email protected] or newer:

npx -y context-first-mcp@latest

Older package versions accidentally published a workspace dependency that npm could not install outside the monorepo.

MCP client shows no tools

Try these checks:

Confirm your client is using context-first-mcp@latest
Restart the MCP client after editing configuration
Clear stale npx cache entries if your client keeps launching an old version
Run node --version and confirm it is Node.js 18 or newer

MCP Registry metadata

MCP name: io.github.XJTLUmedia/context-first-mcp

This npm package includes mcpName in package.json so it can be validated by MCP Registry metadata that points to context-first-mcp as the npm stdio package.

License

MIT