使用说明

MCP脑

在Cloudflare Workers上运行的个人第二大脑。一切都是语义知识图中的一个节点——思想、任务、人、书籍、书签以及您定义的任何自定义类型。节点根据含义自动链接，智能地进行重复数据消除，并且可以通过模型上下文协议（MCP）.

专为AI代理构建。你和你的人工智能助手交谈，它会为你记住一些事情——没有手动笔记，没有应用程序切换，没有摩擦。

运作原理

You ←→ AI Assistant ←→ MCP Brain (Cloudflare Worker) ←→ Supabase Postgres + pgvector
                              ↕
                     Cloudflare Workers AI
                  (embeddings, dedup, synthesis)

您与AI助手（Claude、GPT或任何兼容MCP的客户端）交谈
助手使用MCP工具保存、搜索和连接您的知识
新节点会自动嵌入、消除重复并链接到相关节点
所有内容都存储在您自己的Supabase Postgres数据库中，并带有矢量搜索功能

特性

语义搜索 --按意义查找节点，而不仅仅是关键字。适用于任何语言。
自动链接 --新节点会自动连接到语义相似的现有节点（余弦相似度0.5-0.92）。
三层重复数据删除 --完全匹配→ 高相似度自动合并（>0.85）→LLM确认合并（0.5-0.85）→创建新。
灵活的类型 --使用元数据架构定义任何节点类型。没有船——你创造你需要的东西（思想、行动、人、书签等）。
标签分类 --用标签组织。标签可以标记为“项目”进行项目管理。
图形探索 --遍历连接，找到被遗忘的节点，整合链接上下文中的稀疏配置文件。
技能体系 --存储可重用的指令集（人物角色、写作风格、工作流），您的AI代理可以加载和采用这些指令集。
日常维护 --Cron作业会自动修剪薄弱环节。
OAuth+neneneba API密钥身份验证 -与基于浏览器的MCP客户端（OAuth）和CLI/API客户端（承载令牌）配合使用。

先决条件

您需要在两个平台上使用免费帐户：

云耀 --免费计划包括Workers、Workers AI和KV
Supabase --免费计划包括带有pgvector的Postgres

设置

1.克隆并安装

git clone https://github.com/YOUR_USERNAME/mcp-brain.git
cd mcp-brain
pnpm install

2.设置Supabase

在以下位置创建新项目网站 supabase.com
首选 SQL编辑器 并运行以下命令以启用pgvector并创建所有表：

-- Enable pgvector
create extension if not exists vector;

-- Node types (e.g. thought, action, person, bookmark)
create table mb_node_types (
  name text primary key,
  description text not null,
  schema jsonb not null default '{}',
  created_at timestamptz not null,
  embedding vector(1024)
);
create index mb_node_types_embedding_idx on mb_node_types
  using hnsw (embedding vector_cosine_ops);

-- Nodes (the actual knowledge)
create table mb_nodes (
  id uuid primary key,
  type text not null references mb_node_types(name),
  metadata jsonb not null default '{}',
  created_at timestamptz not null,
  embedding vector(1024),
  access_count integer not null default 0,
  last_accessed timestamptz
);
create index mb_nodes_type_idx on mb_nodes(type);
create index mb_nodes_created_at_idx on mb_nodes(created_at);
create index mb_nodes_embedding_idx on mb_nodes
  using hnsw (embedding vector_cosine_ops);

-- Links between nodes (bidirectional, scored)
create table mb_node_links (
  node_a_id uuid not null references mb_nodes(id),
  node_b_id uuid not null references mb_nodes(id),
  label text,
  metadata jsonb not null default '{}',
  created_at timestamptz not null,
  score real not null default 0.5,
  primary key (node_a_id, node_b_id)
);
create index mb_node_links_a_idx on mb_node_links(node_a_id);
create index mb_node_links_b_idx on mb_node_links(node_b_id);
create index mb_node_links_score_idx on mb_node_links(score);

-- Tags
create table mb_tags (
  name text primary key,
  kind text not null default 'tag',
  created_at timestamptz not null,
  embedding vector(1024)
);
create index mb_tags_embedding_idx on mb_tags
  using hnsw (embedding vector_cosine_ops);

-- Node ↔ Tag junction
create table mb_node_tags (
  node_id uuid not null references mb_nodes(id),
  tag_name text not null references mb_tags(name),
  primary key (node_id, tag_name)
);

-- Key-value settings
create table mb_settings (
  key text primary key,
  value jsonb not null
);

-- Skills (reusable instruction sets)
create table mb_skills (
  name text primary key,
  description text not null,
  content text not null,
  embedding vector(1024),
  created_at timestamptz not null,
  updated_at timestamptz not null
);
create index mb_skills_embedding_idx on mb_skills
  using hnsw (embedding vector_cosine_ops);

获取数据库连接字符串：
- 首选 项目设置 → 数据库
- 复制 连接字符串 （URI格式）在“连接池”下——它看起来像：
```
postgresql://postgres.xxxx:password@aws-0-region.pooler.supabase.com:6543/postgres
```
- 确保 连接池 已启用（会话模式）

3.设置Cloudflare

如果您还没有安装wrangler： pnpm add -g wrangler
登录： wrangler login
为OAuth状态创建KV命名空间：

wrangler kv namespace create OAUTH_KV

复制 id 从输出和更新 wrangler.jsonc:

{
  "kv_namespaces": [
    {
      "binding": "OAUTH_KV",
      "id": "YOUR_KV_NAMESPACE_ID"
    }
  ]
}

设定你的秘密：

# Your Supabase connection string (the pooler URI from step 2)
wrangler secret put SUPABASE_DB_URL

# An API key you choose — this is your password to the brain
wrangler secret put BRAIN_API_KEY

选择任何结实的绳子 BRAIN_API_KEY --您将使用它进行身份验证。

4.部署

pnpm run deploy

你的大脑现在处于活动状态 https://mcp-brain.YOUR_SUBDOMAIN.workers.dev.

5.地方发展（可选）

创建一个 .dev.vars 项目根目录下的文件：

SUPABASE_DB_URL=postgresql://postgres.xxxx:password@aws-0-region.pooler.supabase.com:6543/postgres
BRAIN_API_KEY=your-secret-key

然后运行：

pnpm run dev

连接您的AI助手

MCP Brain公开了一个MCP服务器。任何兼容MCP的客户端都可以连接到它。

克劳德桌面/Claude.ai

添加到MCP服务器配置中：

{
  "mcpServers": {
    "mcp-brain": {
      "url": "https://mcp-brain.YOUR_SUBDOMAIN.workers.dev/mcp/oauth",
      "type": "streamable-http"
    }
  }
}

当您首次连接时，您的浏览器将打开一个授权页面。输入你的 BRAIN_API_KEY 以进行身份验证。为了方便起见，密钥可以保存在浏览器的本地存储中。

Claude Code/CLI客户端

CLI客户端可以跳过OAuth，直接使用Bearer令牌身份验证：

{
  "mcpServers": {
    "mcp-brain": {
      "url": "https://mcp-brain.YOUR_SUBDOMAIN.workers.dev/mcp",
      "type": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_BRAIN_API_KEY"
      }
    }
  }
}

其他MCP客户端

MCP Brain支持两种身份验证方法：

方法	端点	用例
OAuth 2.0	`/mcp/oauth`	基于浏览器的客户端（Claude Desktop，Claude.ai）
持有者令牌	`/mcp`	CLI工具、脚本、API调用

对于Bearer auth，设置标头： Authorization: Bearer YOUR_BRAIN_API_KEY

认证

OAuth流（浏览器客户端）

客户端在以下位置启动OAuth /mcp/oauth
用户被重定向到 /authorize --一个简单的HTML表单
用户输入他们的 BRAIN_API_KEY
成功后，会发出OAuth令牌，并将客户端重定向回
后续请求会自动使用OAuth令牌

授权页面支持将密钥保存在浏览器本地存储中，这样您就不会每次都重新输入。

承载令牌（CLI/API）

发送您的 BRAIN_API_KEY 作为不记名代币：

curl -X POST https://mcp-brain.YOUR_SUBDOMAIN.workers.dev/mcp \
  -H "Authorization: Bearer YOUR_BRAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

MCP工具参考

MCP Brain展示了20种工具，分为5类：

类型管理

工具	说明
`create_type`	使用元数据模式定义新的节点类型（例如“配方”、“目标”）
`list_types`	列出所有节点类型及其模式
`update_type`	更新类型的描述或架构
`delete_type`	删除类型（如果存在该类型的节点，则失败）

节点CRUD

工具	说明
`create_node`	保存节点--自动重复数据消除、自动链接、解析标签
`search_nodes`	使用过滤器（类型、标签、日期、排序）进行语义+时间搜索
`update_node`	更新元数据（合并）或标签（替换）
`delete_node`	删除节点及其所有链接/标签
`batch_update`	一次最多在50个节点上添加/删除标签

图

工具	说明
`link_manager`	手动创建或删除节点之间的链接
`explore_connections`	浏览节点的连接，按最强/最弱排序

发现

工具	说明
`list_tags`	列出所有带有计数和种类的标签，可按类型或种类过滤
`update_tag`	重命名标签或更改其类型（例如标记为“项目”）
`forgotten_nodes`	您可能忘记的最难访问的节点
`consolidate_node`	人工智能驱动：从链接的节点中提取事实，以丰富稀疏的配置文件
`get_stats`	大脑概述：按类型统计的节点数、总链接数、总标签数
`set_setting`	配置大脑设置（当前：时区）

技能

工具	说明
`list_skills`	列出所有存储的技能
`load_skill`	加载技能说明供AI采用
`manage_skill`	创建、更新或删除技能

系统提示

MCP Brain包括系统提示，教你的AI助手如何自然地使用大脑。选择一个适合您的设置：

文件	描述
`system-prompt-base.md`	完整的行为指南——大脑使用、反阿谀奉承、反应风格。良好的默认设置。
`system-prompt-claude-code.md`	Claude Code中开发会话的轻量级版本。专注于保存设计决策和架构见解。
`system-prompt-tiny.md`	最小版本（约50行）适用于具有小上下文窗口的本地模型（LM Studio、Ollama等）。

如何使用它们

克劳德桌面/Claude.ai： 将所选系统提示的内容复制到客户端设置中的“自定义说明”或“系统提示”字段中。

克劳德代码： 这 system-prompt-claude-code.md 内容进入 ~/.claude/CLAUDE.md （您的全局指令文件）。

LM工作室/Ollama/当地模特： 使用 system-prompt-tiny.md 作为系统消息。它针对小型上下文窗口进行了优化。

API使用： 将系统提示内容作为 system API调用中的消息。

系统提示做什么

所有提示都指示AI：

静默初始化 --在对话开始时，搜索用户身份、最近的上下文、待处理的任务和标签分类
主动保存 --当你分享一个想法、决定、任务或提到一个人时，人工智能会自动保存它，而不会询问
先搜索再猜测 --对于任何个人问题，人工智能都会先检查大脑
更正更新 --如果你纠正了一个事实，人工智能会立即更新大脑
保持隐形 --AI从不公开节点ID、工具名称或数据库内部

建筑

人工智能模型（Cloudflare Workers AI）

所有AI处理都在Cloudflare的免费Workers AI层上运行：

型号	用途
`@cf/baai/bge-m3`	嵌入（1024个dim向量）-多语言，用于所有语义操作
`@cf/openai/gpt-oss-20b`	推断决策——快速LLM确认/拒绝0.5-0.85相似性范围内的合并
`@cf/qwen/qwq-32b`	综合——从链接节点中提取事实和连接以进行整合

重复数据删除（3层）

创建节点、标记或类型时，系统会防止重复：

精确匹配 --如果已存在相同的名称/内容，请直接合并
自动合并（>0.85余弦相似度） --高置信度复制，无需询问即可合并
LLM确认（0.5-0.85） --范围不明确，LLM决定是否匹配
0.5以下 --绝对是新的，创造它

自动链接

将新节点与所有现有节点进行比较。余弦相似度在0.5到0.92之间的任何一对都会自动链接。链接得分等于相似度。低于0.92的链接不会被创建（太相似了——可能是同一件事，由dedup处理）。链接是双向的。

日常维护

cron作业每天在UTC凌晨3点运行，并删除分数低于 prune_threshold 设置（默认值：0.2）。这消除了随着时间的推移而积累的弱连接。

设置

通过配置 set_setting 工具：

设置	说明	默认值
`timezone`	用于日期查询的IANA时区（例如“欧洲/巴黎”）	无（需要 `since` 过滤器）

内部设置（自动管理）：

设置	说明	默认值
`decay_factor`	合并期间应用于链接分数的乘数	0.7
`prune_threshold`	低于此分数的链接将按每日cron	0.2进行修剪

项目结构

src/
├── index.ts        # Entry point: OAuth provider, MCP handler, cron
├── mcp.ts          # All 20 MCP tool registrations
├── nodes.ts        # Node CRUD, search, auto-linking, consolidation
├── types.ts        # Node type management
├── dedup.ts        # 3-tier deduplication (types, nodes, tags)
├── ai.ts           # Workers AI calls (embeddings, LLM, synthesis)
├── schema.ts       # Drizzle ORM schema (7 tables)
├── database.ts     # Supabase postgres.js connection
├── settings.ts     # KV-cached settings layer
├── validation.ts   # Metadata schema validation
├── skills.ts       # Skills CRUD
└── env.ts          # Environment interface, thresholds

system-prompt-base.md        # Full system prompt
system-prompt-claude-code.md # Dev session variant
system-prompt-tiny.md        # Minimal for local models
wrangler.jsonc               # Cloudflare Workers config

最佳结果提示

入门

部署后，大脑是空的。首先创建所需的节点类型：

“为想法和见解创建一个‘思考’类型，为任务创建一个“行动”类型，为我提到的人创建一个'人'类型，为链接创建一个'书签'类型。”

人工智能将使用合理的模式创建这些。您可以稍后进行自定义。

自然使用

你不需要明确地告诉你的人工智能“保存到大脑”——系统提示会处理这个问题。自然地说话：

“由于矢量支持，我决定使用Postgres而不是SQLite” → 保存为一个想法
“提醒我下周更新文档” → 另存为操作
“我在会议上遇到了Sarah，她在Stripe从事分布式系统工作” → 保存为人
“看看这篇文章：https://example.com/good-read" → 另存为书签

标签和项目

标签自然地出现了。AI在可能的情况下重用现有的标签。要跟踪项目，请执行以下操作：

“将‘mcp-brain’标记为项目标签。”

然后随时问“我的项目是什么？”。

重新发现

随着时间的推移，大脑变得更有价值。尝试：

“我忘了什么？” --忽略节点的曲面
“这周我在想什么？” --近期思考
“X是如何连接到Y的？” --图形探索
“建立Sarah的个人资料” --整合链接到人员节点的所有内容

成本

在免费等级上：

Cloudflare员工：100000次请求/天免费
Cloudflare人工智能：自由层包括对BGE-M3、GPT-OSS-20B和QWQ-32B的慷慨推理限制
Supabase：500MB数据库，1GB文件存储空间

对于个人使用，您不太可能达到任何限制。

许可证

麻省理工学院