使用说明

Agnovat MCP 服务器

版本： 1.0.0 最小可行性产品（MVP） 项目代码： AGNOVAT-MCP-MVP 翻译为中文可以是：“AGNOVAT-MCP-MVP（注：此为专有名词或特定项目/产品的名称，直接保留原样，若需解释性翻译，可为‘AGNOVAT的MCP-MVP（最小可行产品）’，但具体含义需根据上下文确定）”。不过，通常情况下，如果这是一个特定的项目、产品或技术名称，直接保留原名并在必要时加以解释会更为合适 状态： 第四阶段 - MCP（多项目控制计划/主控制计划等，具体含义根据上下文确定）集成完成 ✅

概述

一个针对NDIS（国家残疾保险计划）参与者支持管理的健壮型模型上下文协议（MCP）服务器。该服务器通过符合MCP标准的接口，提供了32项全面工具，用于管理客户、目标、活动、利益相关者、班次记录以及仪表板分析。

使命宣言

构建一个可扩展的MCP服务器，用于支持NDIS（网络数据采集与服务接口）参与者管理，该服务器可将文档编制时间缩短40%，同时提高目标跟踪的准确性和交接沟通的效率。

特点 ✅

核心功能（完整）

✅ 客户管理创建、检索、更新、停用和搜索客户资料
✅ 目标追踪通过自动化进度追踪和风险检测来管理NDIS（国家残疾保险计划）参与者的个人目标
✅ 活动日志记录记录支持活动，并关联目标及日期范围查询
✅ 换班笔记/交接班记录全面的班次记录文档，拥有24小时编辑窗口
✅ 利益相关者管理追踪支持人员、协调员及其他利益相关者
✅ 仪表盘实时概览，包含聚合指标及风险目标检测

MCP 集成（完成）

✅ 32 MCP 工具对所有实体执行完整的CRUD操作（创建、读取、更新、删除）
✅ 6 个资源端点基于URI的直接实体访问
✅ 6个提示模板常见任务的引导式工作流程
✅ MCP协议合规性工具、资源和提示已全面实施

技术特性（完整版）

✅ 带严格类型检查的TypeScript
✅ 基于JSON的数据存储，支持文件锁定
✅ 原子写入以防止数据损坏
✅ 备份和恢复功能
✅ 全面的错误处理
✅ 保护个人身份信息（PII）的安全日志记录

项目结构

agnovat-mcp-server/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── tools/                # MCP tool implementations
│   ├── resources/            # MCP resource handlers
│   ├── prompts/              # MCP prompt templates
│   ├── storage/              # Data persistence layer
│   ├── models/               # Data models and types
│   ├── validation/           # Zod schemas and validation
│   └── utils/                # Utilities and helpers
├── data/                     # JSON data storage
├── tests/                    # Test suite
├── docs/                     # Documentation
└── plan.md                   # Detailed development plan

开发环境设置

先决条件

Node.js 18及以上版本
npm 或 pnpm

安装

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

可用脚本

npm run build - 将TypeScript编译为JavaScript
npm run dev - 开发用的监视模式
npm start - 运行编译后的服务器
npm test - 运行测试套件
npm run test:watch - 在监视模式下运行测试
npm run test:coverage - 生成覆盖率报告
npm run lint - 代码整洁度（或代码规范性检查）
npm run lint:fix - 检查并自动修复问题
npm run format - 使用 Prettier 格式化代码
npm run type-check - 检查 TypeScript 类型而不出发（即不生成代码）

测试MCP服务器

MCP服务器可以无需前端，直接通过像Claude Desktop这样的AI应用进行测试。

见 TESTING_GUIDE.md 翻译为中文是：《测试指南》.md（文件名）完整的测试说明，包括：

Claude Desktop的配置与设置
使用自然语言进行交互式测试
用于调试的MCP检查器
测试了全部32个工具、6个资源和6个提示
性能测试和生产准备检查清单

快速入门Claude桌面版

安装 Claude Desktop（可译为“Claude桌面版”或保持原样，根据上下文决定是否需要具体化为某个平台或版本的名称）
构建项目： npm run build
添加到Claude桌面配置（~/Library/Application Support/Claude/claude_desktop_config.json （在 macOS 上）：

{
  "mcpServers": {
    "agnovat": {
      "command": "node",
      "args": ["/absolute/path/to/agnovat-mcp/dist/index.js"],
      "env": {
        "STORAGE_TYPE": "json",
        "DATA_DIR": "/absolute/path/to/agnovat-mcp/data"
      }
    }
  }
}

重启Claude桌面版
开始测试：“你能为我创建一个新的NDIS客户端吗？”

MCP 工具（共32个）

客户端工具（6）

create_client - 创建带有验证的新客户档案
get_client - 获取带有汇总统计信息的客户端
list_clients - 列出/搜索客户并应用筛选条件
update_client - 更新客户信息
deactivate_client - 带验证的软删除
search_clients - 全文名称搜索

目标工具（6）

create_goal - 制定带有里程碑的NDIS目标
get_goal - 获取包含详细信息的目标
list_goals - 按状态、类别、客户过滤
update_goal - 更新目标属性
update_goal_progress - 更新进度并提供自动状态建议
archive_goal - 归档已完成/已终止的目标

活动工具（6）

create_activity - 记录支持活动并关联目标
get_activity - 获取包含详细信息的活动
list_activities - 按日期、状态、客户、目标筛选
update_activity - 更新活动信息
get_activities_by_date_range - 按日期范围查询
get_upcoming_activities - 获取接下来N天的日程安排

利益相关者工具（6）

create_stakeholder - 创建支持工作人员/协调员的个人资料
get_stakeholder - 附带活动摘要进行检索
list_stakeholders - 按角色、激活状态筛选
update_stakeholder - 更新利益相关者信息
deactivate_stakeholder - 对利益相关者进行软删除
search_stakeholders - 全文名称搜索

Shift 笔记工具（6）

create_shift_note - 随附相关活动/目标的文件转移
get_shift_note - 获取包含详细信息的班次记录
list_shift_notes - 按客户、利益相关者、日期筛选
update_shift_note - 在24小时窗口期内进行编辑
get_recent_shift_notes - 获取最近N次班次的笔记
get_shift_notes_for_week - 获取每周的班次记录

仪表盘工具（2）

get_dashboard - 聚合指标、处于风险中的目标、最近活动
get_client_summary - 客户概况及目标进度
get_statistics - 高级系统统计信息

MCP资源公司（6）

通过URI访问实体：

client:///{client_id} - 客户资料
goal:///{goal_id} - 目标详情
activity:///{activity_id} - 活动详情
shift_note:///{shift_note_id} - 班次备注
stakeholder:///{stakeholder_id} - 利益相关者概况
dashboard://summary - 仪表盘数据

MCP 提示（6）

引导式工作流程：

create_shift_note_for_client - 分步骤的交接班记录
review_client_progress - 全面进展审查
plan_activity_for_goal - 活动规划助手
handover_summary - 交接报告生成
weekly_report - 为客户/组织提供每周总结
goal_risk_review - 风险目标分析及行动计划

开发阶段

第一阶段：基础 ✅

✅ 项目设置与配置
✅ 数据模型和Zod模式（7个实体）
✅ 带文件锁定的JSON存储
✅ 实用工具和错误处理

第二阶段：核心工具 ✅

✅ 客户管理工具（6项功能）
✅ 目标管理工具（7项功能）
✅ 活动管理工具（6项功能）
✅ 利益相关者管理工具（6项功能）

第三阶段：转移笔记与仪表板 ✅

✅ 切换笔记工具（6种功能）
✅ 仪表板聚合功能（3项功能）
✅ 目标风险检测
✅ 每周/每日总结

阶段4：MCP集成 ✅

✅ MCP服务器入口点
✅ 工具注册（32个工具）
✅ 资源端点（6个资源）
✅ 提示模板（6个提示）

阶段5：测试与文档编制（接下来）

⏳ 单元测试（目标：80%+覆盖率）
⏳ 集成测试
⏳ 端到端测试
⏳ API文档
⏳ 用户指南
⏳ 与支持工作人员进行UAT（用户验收测试）

配置

环境变量

STORAGE_TYPE存储后端类型 (json 或者 convex，默认： json）
DATA_DIRJSON数据存储目录（默认： ./data)
CONVEX_URL凸部署URL（如果...则为必填项） STORAGE_TYPE=convex)

数据存储选项

JSON 文件存储（默认）

基于本地文件的存储
原子写入以防止数据损坏
文件锁定以支持并发访问
用于性能提升的内存缓存
每日自动备份至 data/backups/

凸数据库（可选）

基于云的实时数据库
自动扩展和复制
内置认证和文件存储功能
使用生成的 TypeScript 类型实现类型安全
提供免费层级以供开发使用

见 `CONVEX_SETUP.md` 翻译成中文为：“凸优化设置说明文件（或：凸优化配置指南）”。这里，“CONVEX”指的是“凸优化”（Convex Optimization），“SETUP”通常指的是“设置”或“配置”，而“.md”是Markdown文件格式的扩展名，常用于编写技术文档或说明文件。因此，整个文件名可以理解为一个关于如何设置或配置凸优化的Markdown格式说明文件关于详细的Convex集成指南。

示例用法

创建客户端

{
  "name": "John Smith",
  "date_of_birth": "1995-03-15",
  "ndis_number": "43012345678",
  "support_notes": "Requires assistance with daily living skills"
}

设定一个目标

{
  "client_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Independent meal preparation",
  "category": "daily_living",
  "target_date": "2025-12-31",
  "description": "Develop skills to prepare simple meals independently",
  "milestones": [
    "Learn basic kitchen safety",
    "Prepare cold meals independently",
    "Cook simple hot meals with guidance"
  ]
}

记录转变过程

{
  "client_id": "550e8400-e29b-41d4-a716-446655440000",
  "stakeholder_id": "660e8400-e29b-41d4-a716-446655440001",
  "shift_date": "2025-10-18",
  "start_time": "14:00",
  "end_time": "18:00",
  "general_observations": "Client was engaged and motivated today. Great progress on meal prep skills.",
  "activity_ids": ["770e8400-e29b-41d4-a716-446655440002"],
  "goals_progress": [
    {
      "goal_id": "880e8400-e29b-41d4-a716-446655440003",
      "progress_notes": "Successfully prepared pasta with minimal guidance. Required help with timing.",
      "progress_observed": 5
    }
  ],
  "mood_wellbeing": "Positive mood, expressed pride in achievements",
  "handover_notes": "Continue working on timing and multitasking in kitchen"
}

业务规则

数据完整性

所有ID均为UUID v4格式
ISO 8601格式的时间戳（协调世界时）
对所有关系进行外键验证
仅进行软删除（不进行物理删除）

验证规则

无法为非活跃客户创建目标
无法停用具有活跃目标的客户端
活动必须属于有效的客户和利益相关者
目标和活动必须属于同一客户
排班备注只能在排班日期后的24小时内编辑
NDIS编号在所有活动客户端中必须唯一

目标风险检测

当以下情况发生时，目标会被标记为“处于风险之中”：

进度 < 50% 且
距离目标日期的天数 ≤ 14

自动状态建议

根据进度自动建议目标状态：

0%： not_started
1-99%: in_progress
100%： achieved

绩效目标

简单查询：小于500毫秒
仪表盘加载时间：< 2秒
支持100多个客户端，500多个目标，5000多个活动
内存缓存将重复查询时间减少了80%以上

安全与隐私

PII保护

日志中自动隐去敏感字段
错误消息中不包含PII（个人身份信息）
对所有用户数据进行输入清理
NDIS号码已验证并受保护

敏感字段（永不记录）

password， token， secret， apiKey
ndis_number， email， phone
date_of_birth， primary_contact

错误处理

带有代码的自定义错误类：

ValidationError - 输入验证失败
NotFoundError - 实体未找到
ConflictError - 违反业务规则
StorageError - 数据持久化失败
AuthorizationError - 权限被拒绝（例如，编辑窗口已过期）

技术栈

语言TypeScript 5.9+（严格模式）
运行时Node.js 18及以上版本
MCP SDK（MCP软件开发工具包）@modelcontextprotocol/sdk ^1.20
验证Zod ^3.25
存储使用 fs-extra ^11.3 的 JSON 文件
锁定proper-lockfile ^4.1
日期date-fns ^4.1
测试Jest ^30.2
**Linting（代码检查/静态分析）**ESLint ^9.38 + Prettier ^3.6

代码质量标准

TypeScript 严格模式已启用
不 any 允许的类型
公共API的100% JSDoc覆盖率
ESLint + Prettier 强制执行
单一职责原则
依赖注入模式

路线图

第五阶段：测试与润色（当前阶段）

所有工具的单元测试
工作流的集成测试
关键路径的端到端（E2E）测试
API文档
用户指南

未来的改进/增强功能

PostgreSQL 存储选项
高级报告与分析
电子邮件/短信通知
日历集成
移动应用支持
多租户（或多租户架构）
基于角色的访问控制
导出为PDF/Excel

贡献

这是一个最小可行性产品（MVP）项目。请参考 plan.md 关于详细开发规则和编码标准。

提交信息格式

<type>(<scope>): <subject>

Types: feat, fix, docs, test, refactor, perf, chore

许可证

ISC（International Space Command，国际空间司令部，注：具体名称可能根据上下文有所不同，此处为一种可能的翻译）

支持

如遇问题或疑问，请参阅项目文档或联系开发团队。

版本1.0.0 最小可行性产品（MVP） 最后更新时间2025年10月18日 当前阶段第四阶段完成 - MCP（多点控制单元/管理控制协议等，具体根据上下文确定）集成 ✅ 下一阶段第五阶段 - 测试与文档编制