Frinus MCP服务器
> 刹车 + 噪音 --克劳德代理人与…之间的认知记忆桥梁 弗里纳斯 平台。
MCP(模型上下文协议)服务器,公开 70工具 涵盖认知记忆、工作记忆、会话、代理、L0-L3知识层次结构、编排任务和培训管道。服务器使用stdio,由Claude Desktop、Claude Code和任何支持MCP的客户端使用。
- 版本: 3.1.0
- 工具: 70(见 工具参考)
- 后端: 内存引擎(
:8001)+控制平面(:8000)+代理服务(:8002) - 公共镜像: https://github.com/frinus-ai/frinus-mcp
规则零——MCP是强制性的
Frinus MCP 是 代理人的长期记忆、身份和智力。没有它,模型在会话之间是无状态的。每个与Frinus整合的克劳德特工都必须:
- 验证对话开始时MCP工具是否可用(例如。
session_start,memory_search,search_with_attention). - 如果无法访问,请向用户显示警告: “MCP Frinus未连接。长期内存功能不可用。”
- 执行 BOOT协议(P1) 在回答任何非琐碎的问候之前。
- 通过以下方式持续学习
memory_store在结束富有成效的会议之前。
完整的协议集存在于全球 CLAUDE.md (Frinus组织),总结如下 7议定书.
需求
- Node.js 18+
- Frinus堆栈可达(内存引擎、控制平面、代理服务)
- 个人API密钥(
sk-frinus-...)与租户绑定
安装```bash
npm install
npm run build
该建筑发出 `dist/index.js`,准备连接到克劳德桌面/Claude代码。
## 环境变量
|变量|默认值|描述|
|----------|---------|-------------|
| `FRINUS_API_KEY` | **必需的** |个人API密钥(`sk-frinus-...`).在启动时解析租户+用户身份。 |
| `MEMORY_SERVICE_URL` | `http://localhost:8001` |内存引擎基本URL|
| `FRINUS_CP_URL` | `http://localhost:8000` |控制平面基本URL(世界、组织、计费)|
| `AGENT_SERVICE_URL` | `http://localhost:8002` |代理服务基础URL(代理、调用、技能)|
| `FRINUS_MEMORY_API_KEY` |--|遗留问题回退 `FRINUS_API_KEY` |
生产端点(Frinus SaaS):```bash
MEMORY_SERVICE_URL=https://frinus-memory.rdxsec.com.br
FRINUS_CP_URL=https://frinus-api.rdxsec.com.br
AGENT_SERVICE_URL=https://frinus-agents.rdxsec.com.br
FRINUS_API_KEY=sk-frinus-...
克劳德桌面/Claude代码配置
将服务器添加到MCP客户端配置中:```json
{
"mcpServers": {
"frinus": {
"command": "node",
"args": ["/absolute/path/to/mcp/dist/index.js"],
"env": {
"FRINUS_API_KEY": "sk-frinus-...",
"MEMORY_SERVICE_URL": "https://frinus-memory.rdxsec.com.br",
"FRINUS_CP_URL": "https://frinus-api.rdxsec.com.br",
"AGENT_SERVICE_URL": "https://frinus-agents.rdxsec.com.br"
}
}
}
}
Claude桌面配置路径: `~/.config/claude/claude_desktop_config.json` (Linux)/ `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)。
Claude代码配置路径: `~/.claude.json` 在...之下 `mcpServers`.
启动时,服务器通过验证API密钥 `/auth/me` 并解析租户组织ID+登录用户。失败会中止进程 `[FATAL]` 因此客户端会显示错误。
## 7议定书
|协议|时间|工具|目的|
|----------|------|-------|---------|
| **P1--开机** |每次会议开始| `session_start`, `working_memory_get`, `search_with_attention` |负载标识+最近状态+相关上下文|
| **P2--咨询** |在采取任何行动之前| `search_with_attention`, `session_context`, `memory_reinforce`, `memory_weaken` |检索、评价和强化相关记忆|
| **P3——计划** |计划任务| `memory_store(procedural)`, `working_memory_add`, `stream_capture` |坚持计划、工作状态和架构决策|
| **P4--捕获** |每2-3次交互| `heartbeat_tick`, `working_memory_add`, `memory_store(episodic)`, `stream_capture` |持续记录进度、错误、模式|
| **P5——学习** |新知识| `training_teach`, `training_qa`, `training_upload`, `training_stats`, `stream_process`, `sleep_run` |教授事实/程序并运行整合周期|
| **P6——审计** |维护保养| `consolidation_detect_conflicts`, `consolidation_resolve_conflict`, `consolidation_detect_redundant`, `hierarchy_consolidate` |检测冲突、冗余并整合记忆|
| **P7--关闭** |会议结束| `session_summary`, `stream_process`, `memory_store`, `hierarchy_consolidate`, `session_end` |总结、推广流水作业、坚持学习|
详细的协议脚本存在于代理的 `CLAUDE.md`将上表视为每个Frinus综合代理商必须遵守的合同。
## 工具参考
70个按领域分组的工具。每个工具都返回文本内容;有效载荷跟随MCP `Tool` spec.完整的JSON模式存在于 `src/tools/definitions.ts`.
### 记忆(7)
认知长期记忆:情景(发生了什么)、语义(我知道什么)、程序(如何做事)。
|工具|说明|
|------|-------------|
| `memory_store` |创造记忆。 `agent_id`, `content` 必修的。 `memory_type` ∈{情景、语义、程序}。 `scope` ∈{用户、代理、宇宙、组织}。 `importance` 0–1. |
| `memory_search` |语义相似性搜索。过滤器: `agent_id`, `memory_types`, `limit`. |
| `memory_get` |通过以下方式获取内存 `memory_id` (完整内容、元数据、相关性)。 |
| `memory_list` |列出一段回忆 `agent_id` 带可选类型过滤器。 |
| `memory_delete` |通过以下方式永久删除内存 `memory_id`. |
| `memory_reinforce` |增强有用记忆的相关性(`memory_id`, `boost` 0–1,默认值为0.1)。 |
| `memory_weaken` |惩罚过时的记忆(`memory_id`, `penalty` 0–1,默认值0.2)。 |
### 工作记忆(3)
短期、受上下文约束的状态。米勒定律:每个上下文最多7个项目,最古老的自动驱逐。默认TTL 30分钟(最多2小时)。
|工具|说明|
|------|-------------|
| `working_memory_get` |加载上下文的当前状态。总是在任务开始时打电话。 |
| `working_memory_add` |保持现状。上下文格式: `agent:{uuid}`, `universe:{uuid}`, `organization:{uuid}`. |
| `working_memory_clear` |删除上下文中的所有项目。 |
### 会议(5)
会话=流、工作内存和捕获的逻辑容器。
|工具|说明|
|------|-------------|
| `session_start` |为代理启动会话。退货 `session_id`.支持 `parent_session_id` 用于子代理继承。 |
| `session_end` |结束会议并完成总结。 |
| `session_context` |工作+长期检索相结合,通过提取会话主题进行增强。 |
| `session_summary` |生成一个结构化的回顾(决策、学习、未决事项)。 |
| `session_clear` |在不结束会话的情况下擦除会话的工作状态|
### 流(4)
连续捕获管道。项目被批量处理、评分,重要的项目被提升为永久记忆。
|工具|说明|
|------|-------------|
| `stream_capture` |记录与会话相关的输入/输出/内部注释。 |
| `stream_get_session` |回放每个捕获的项目 `session_id`. |
| `stream_get_recent` |最近跨会话流式传输项目(可过滤)。 |
| `stream_process` |将待处理的项目提升到长期内存中(手动触发;调度程序也每5分钟运行一次)。 |
### 背景与注意力(2)
|工具|说明|
|------|-------------|
| `memory_get_context` |为任务描述构建一个标记约束的上下文窗口。 |
| `search_with_attention` |具有任务类型感知权重的RAG。 `task_type` ∈{实现、调试、部署、文档、审查}驱动memory_type权重。 |
### 用户(2)
|工具|说明|
|------|-------------|
| `user_register` |在内存系统中注册用户(幂等)。 |
| `user_get_context` |检索组合用户记忆和租户上下文。 |
### 维护(2)
|工具|说明|
|------|-------------|
| `heartbeat_tick` |代理的廉价报价——推动相关性衰减和轻量级整合。 |
| `sleep_run` |触发睡眠周期。 `phases` ⊆{评价、遗忘、巩固、相关性}。反映调度程序的正常/深度睡眠。 |
### 合并(3)
|工具|说明|
|------|-------------|
| `consolidation_detect_conflicts` |高于相似性阈值的表面候选冲突记忆。 |
| `consolidation_resolve_conflict` |保留一个记忆,用书面决议说明取代另一个。 |
| `consolidation_detect_redundant` |查找准备合并或删除的近似重复项。 |
### 内存层次结构(2)
|工具|说明|
|------|-------------|
| `hierarchy_consolidate` |将几个相关的记忆滚动到更高级别的摘要记忆中。 |
| `hierarchy_get_tree` |检查合并树是否有根内存。 |
### 代理商(6)
代理CRUD+编排调用。
|工具|说明|
|------|-------------|
| `agent_create` |创建一个作用域为宇宙/团队的代理(可选地从模板中)。 |
| `agent_list` |列出呼叫者租户中的代理。通过API键自动缩放。 |
| `agent_get` |通过以下方式获取代理 `agent_id`. |
| `agent_update` |更新角色、团队、宇宙等。 |
| `agent_delete` |删除代理。 |
| `agent_invoke` |以编程方式调用具有任务的代理。返回其工具调用和最终答案。由代表团使用。 |
### 宇宙(4)
宇宙=租户范围的知识域。保持L0-L3层次结构。
|工具|说明|
|------|-------------|
| `universe_create` |在调用者的org.Slug+名称+描述中创建一个宇宙。 |
| `universe_list` |列出已解析组织的宇宙|
| `universe_update` |修补一个宇宙(名称、描述)。 |
| `universe_hierarchy` |步行整个L0→ L3树代表一个带有状态图标的宇宙。 |
### 知识层次L0-L3(16)```
Universe
└─ Concept (L0) body of knowledge
└─ Theme (L1) thematic split
└─ Topic (L2) unit of work (status: pending / in_progress / completed)
└─ Point (L3) atomic knowledge unit
每个级别都暴露 create, list, update, delete:
- L0概念:
concept_create,concept_list,concept_update,concept_delete - L1主题:
theme_create,theme_list,theme_update,theme_delete - L2主题:
topic_create,topic_list,topic_update,topic_delete - L3点:
point_create,point_list,point_update,point_delete
topic_update 和 point_update 接受a status 这样代理人就可以标记进展。
培训管道(6)
明确地教授系统——事实、程序、问答对、完整的文件。
| 工具 | 说明 |
|---|---|
training_teach |
注入事实或程序。 type ∈{语义,程序}。 |
training_qa |
火车与 pairs 的 {question, answer}. |
training_upload |
上传文档(file_path, filename)用于大块摄入。 |
training_stats |
语料库的覆盖率统计。 |
training_gaps |
检测到知识差距/主题覆盖不足。 |
training_recent |
最近从训练中吸收了记忆。 |
编排——任务(4)
内存引擎上的任务表驱动多代理编排。
| 工具 | 说明 |
|---|---|
task_create |
创建任务(标题、描述、可选 assigned_agent_id,父任务)。 |
task_get |
获取具有完整状态的任务。 |
task_list |
列出带有筛选器(状态、代理、父级)的任务。 |
task_update |
更新状态、输出或分配。 |
技能(4)
分配给代理的可重用行为。
| 工具 | 说明 |
|---|---|
skill_list |
列举租户中可用的技能。 |
skill_assign |
为代理人附加技能。 |
skill_remove |
将技能从代理中分离出来。 |
skill_agent_list |
列出给定代理所拥有的技能。 |
内存类型
类型 · 用例 · 示例
episodic · 记录发生的事情 · Bug: payment endpoint returned 500. Cause: missing null check on customer.address. Fix: guard + 422 response. File: services/payment.py
semantic · 存储事实和知识 · MemoryResponse now includes universe_id (UUID · None) so the frontend can group memories per universe in the graph view.
procedural · 记录操作程序 · Procedure: rotate-claude-credentials. Steps: 1) aws ecr login, 2) kubectl set image deployment/agent..., 3) verify pod is Ready. Caveat: deployment is named "agent", not "agent-service".
范围
| 范围 | 可见性 | 用例 |
|---|---|---|
user |
仅存储用户 | 个人偏好和历史记录 |
agent |
仅存储代理 | 代理私人笔记 |
universe |
宇宙中的所有代理(部门) | 共享领域知识 |
organization |
租户中的所有代理人 | 组织范围内的程序和事实 |
> 遗产 agent / project / global 望远镜与 project_id宇宙取代了项目,成为组织内部的隔离边界。
最佳实践
内存所需的格式——使未来的检索具有确定性:
- 程序错误
Bug: . Cause: . Fix: . File: - 图案:
Pattern: . When to use: . File: - 程序:
Procedure: . Steps: 1) ... 2) ... 3) .... Caveats:
操作指南:
- 总是先开机。 呼叫
session_start+working_memory_get+search_with_attention在回答之前。 - 使用时加强/削弱。 当回忆起的记忆有帮助时,
memory_reinforce当它出错时,memory_weaken(并替换它)。 - 每2-3圈就抓住一次。
working_memory_add对于国家来说,stream_capture对于决策,memory_store对于结晶的学习。 - 选对了
task_type.search_with_attention对每个任务的内存类型进行加权。debug喜欢偶发性,documentation有利于语义,deploy倾向于程序性。 - 关闭循环。 结束会话
session_summary+stream_process+session_end.快跑sleep_run以便在批次增长时进行更深入的整合。 - 在混乱累积之前进行审计。 周期性的
consolidation_detect_conflicts+consolidation_detect_redundant保持清晰的回忆。
建筑```
+---------------------+ +------------------+ +----------------------+
| Claude Agent / | <---> | Frinus MCP | <---> | Memory Engine |
| Claude Code | stdio | (this server) | HTTPS | (memories, sessions, |
+---------------------+ +------------------+ | hierarchy, tasks) |
| +----------------------+
| |
| v
| +----------------------+
| | PostgreSQL+pgvector |
| | + Apache AGE (graph) |
| +----------------------+
|
+---HTTPS---> Control Plane (universes, orgs)
+---HTTPS---> Agent Service (agents, invocation, skills)
- **记忆引擎** 拥有记忆、工作记忆、会话、流、L0-L3层次结构、训练、睡眠周期、任务、技能。
- **控制平面** 拥有组织、通用、会员、API密钥、账单、凭证、白标签、LLM密钥。
- **代理服务** 拥有代理运行时、工具调度、团队路由、角色、调用。
租户隔离是每个租户的数据库。MCP在启动时从API密钥解析您的租户组织ID-您永远不会通过 `org_id` 手动。
## 发展```
mcp/
src/
index.ts Entry: MCP server, dispatch, auth bootstrap
client/
memory-client.ts HTTP client + identity state for Memory Engine
cp-client.ts HTTP client for Control Plane
agent-client.ts HTTP client for Agent Service
tools/
definitions.ts Tool schemas (70 tools)
handlers.ts Tool handlers (70 handlers)
capture/
interaction-capture.ts Auto stream capture for every tool call
types/
index.ts Shared types
dist/ Compiled output (npm run build)
package.json
tsconfig.json
脚本:bash
npm run build # tsc to dist/
npm run dev # tsx hot reload (src/index.ts)
npm start # node dist/index.js
类型检查:TypeScript 5.6+,ES模块,axios。
许可证
有关许可条款,请参阅存储库根目录。
