A
licenseNot graded
qualityB
maintenanceProvides LLM agents with a structured, queryable, local-first knowledge base with typed documents and full-text search via MCP.
MIT
context-hub
by roy-reed
The server exposes a minimal MCP tool set for querying a local-first context hub: searching context, reading stable references, and inspecting the manifest, with additional lifecycle and safety operations described in the README.
Search: Query context entries by text, filter by
project_idandkinds(constraint, decision, fact, preference, status), setlimit, and paginate withcursor.Read: Retrieve a specific context item by stable
ref, optionally withinclude_historyandmax_charstruncation.Manifest: Inspect public projects, source types, source counts, and source summaries.
Responses include a
context_hubinvocation marker with status, transport, request ID, and project/source metadata.Transports: Works over MCP STDIO (ChatGPT Desktop) and Streamable HTTP with Bearer auth; non-loopback binds require explicit confirmation and TLS/reverse proxy.
Project/lifecycle operations (from README): initialize projects, register/list projects, stable reference pagination, explicit writes, diagnostics, rebuild derived SQLite FTS5 index after deletion, and backup/restore to a new directory.
Safety/validation: Throttled sync, read-only status, single-step safe repairs, synthetic evaluation, real-import preflight, worker guard records, and default-off telemetry.
Import gate: Real memory import remains disabled; dry-run import planning and approval do not auto-register sources.
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., "@context-hubsearch my context files for the latest API design"
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.
Context Hub v0.2
本仓库按 Context Hub v1.1 规格交付本地优先的 v0.2 实现：以 JSONL/Markdown 为事实源， SQLite FTS5 为可重建索引，并通过 MCP STDIO 与 Streamable HTTP 暴露最小工具面。 日常 Loop 提供有节流的同步、只读状态、单步安全修复、合成评测、真实导入预检和外接 worker 保护记录。
首轮开发和验收只使用仓库内测试生成的合成数据，不导入任何既有记忆或个人资料。
当前代码已经用官方 Python MCP SDK 完成本地真实 STDIO、Streamable HTTP 握手、
tools/list 和 context_get 调用。ChatGPT Desktop 可直接注册本地 STDIO 服务；
ChatGPT Web 或远程客户端使用带 Bearer 认证的 HTTPS MCP URL。非回环监听默认拒绝，
必须显式确认公网绑定并配置认证与 TLS（或位于可信 TLS 反向代理之后）。产品侧状态、
纯合成验收入口和人工确认边界记录在
docs/chatgpt-client-status.md。
快速验证
.\.venv\Scripts\python.exe -m pip install -r requirements.lock
.\.venv\Scripts\python.exe -m pip install -e . --no-deps
pwsh -NoLogo -NoProfile -File .\scripts\run_runbook_smoke.ps1
.\.venv\Scripts\python.exe -X utf8 -m unittest discover -s tests -v
.\.venv\Scripts\python.exe -X utf8 scripts\run_loop_acceptance.py --output .context-hub-test-data\loop-acceptance-report.json
.\.venv\Scripts\python.exe -X utf8 scripts\run_multiproject_acceptance.py --output .context-hub-test-data\multiproject-report.json
.\.venv\Scripts\python.exe -X utf8 scripts\run_acceptance.py --output .context-hub-test-data\acceptance-report.json
.\.venv\Scripts\python.exe -X utf8 scripts\verify_desktop_stdio.py --command .\.venv\Scripts\context-hub-mcp.exe --data-dir .\.context-hub-test-data\chatgpt-http-e2e\data --query chatgpt-http-e2e-7f3a91 --project-id desktop-e2e --expected-marker chatgpt-http-e2e-7f3a91 --runs 5PowerShell 冒烟脚本逐条调用手册公开的 CLI，验证初始化、项目注册、清单、检索、稳定 引用分页、显式写入、诊断、删除派生索引后重建，以及备份后恢复到新目录。它只创建 唯一的合成测试目录，结束后删除该目录并保留忽略的 JSON 报告。
多项目验收会在单个临时目录内生成 3 个彼此隔离的项目，验证固定 Top-3 检索集、
项目与类型过滤、分页哈希、源文件变更/删除、历史版本、无损重建，以及本地真实
STDIO 的 manifest → search → read。脚本不读取现有 Context Hub 数据或既有记忆。
Loop 验收在一个临时目录中覆盖两项目隔离、同步节流、单步备份、合成评测、导入计划
快照、1,000,000 token 边界、输出截断元数据、备份恢复和默认关闭遥测。真实记忆导入
闸门目前保持关闭；import-plan --dry-run 和 approve-import 都不会自动注册来源。
安装、只读启动、显式写入、备份恢复和客户端验收步骤见 RUNBOOK.md。
Pi / DeepSeek 的 1,000,000 token 任务上限、截断、重试与墙钟保护实测见
docs/worker-guard-validation.md。
Available Tools
1 toolcontext_getB
Search, read a stable ref, or inspect the public manifest. Responses include a context_hub invocation marker and source summary.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| op | Yes | ||
| ref | No | ||
| kinds | No | ||
| limit | No | ||
| query | No | ||
| cursor | No | ||
| max_chars | No | ||
| project_id | No | ||
| include_history | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| op | Yes | |
| items | No | |
| content | No | |
| projects | No | |
| context_hub | Yes | |
| next_cursor | No |
TDQS
B3.1/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that responses include a context_hub invocation marker and source summary, which is useful. However, it doesn't mention read-only vs mutating behavior, pagination, or error conditions, leaving the behavioral profile incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the three operations and adds a concrete response detail. It is compact and every clause earns its place, though it could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters, 0% schema coverage, no annotations, and no sibling context, the description is too thin. The output schema exists, so return values are covered, but the tool's selection criteria, parameter semantics, and behavioral traits are under-specified for an agent to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only mentions 'stable ref' and 'public manifest' without explaining the parameters. The op enum is self-explanatory, but ref, kinds, limit, query, cursor, max_chars, project_id, and include_history are left entirely to the schema, which has no descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names three distinct operations (search, read, inspect manifest) and a stable ref concept, which is clear enough to distinguish the tool's purpose. However, it doesn't name any sibling tools, so differentiation relies on the op enum rather than explicit contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage contexts by listing operations ('Search, read a stable ref, or inspect the public manifest'), but it doesn't state when to use one op over another or when to prefer an alternative tool. With no siblings and no exclusions, the guidance is adequate but implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
1 tool update
v0.1.0- First observed
context_get
TDQS
B3.2/5.0
Scored across 1 tool
Disambiguation5/5
With only a single tool, there is no possibility of confusing it with another tool. The tool's description clearly covers its purpose without overlapping with anything else.
Naming Consistency5/5
The lone tool 'context_get' follows a clear snake_case convention with a verb_noun pattern. While there is no set to compare against, the name is consistent with common MCP naming practices.
Tool Count2/5
Having only one tool for a context hub is severely under-scoped. The description implies multiple capabilities (search, read, inspect manifest) that would typically be split into separate tools, making the single tool feel like a catch-all.
Completeness2/5
The tool covers read-only operations but lacks any management, listing, or mutation capabilities. For a context hub, one would expect at least tools to create or update contexts, or to list available contexts, which are missing here.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Related MCP Connectors
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Personal context for every AI: search, read, and write back to your private Markdown library.
Person-owned AI memory that learns, not just stores — portable context for any MCP client.
Your versioned memory across every AI tool — context maps, personal memory, and tasks over MCP.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceLocal-first MCP server for indexing and searching research materials (papers, notes, logs, READMEs) using SQLite FTS, with tools for memory management and evidence retrieval.MIT
- AlicenseNot gradedqualityCmaintenanceLocal context management, search engine, and memory for agentic AI via MCP, enabling efficient context retrieval and storage.31 npm4MIT
- AlicenseAqualityBmaintenanceIndexes local Markdown/text files into a SQLite database with vector embeddings and provides MCP tools for semantic search without cloud dependencies.3AGPL 3.0