mcpField
H
harper-mcp

harper-mcp

github.com/harperfast开发390 次安装2 天前更新
代码仓库

关于 harper-mcp

一组指南，介绍如何将 Harper 配置为 MCP 服务，以及设计 MCP 客户端可使用的工具、提示词和资源。内容涵盖连接细节、自动与自定义能力及运行安全。

主要功能

  1. 01配置 application 和 operations 配置
  2. 02说明客户端握手与身份验证
  3. 03生成带 RBAC 过滤的 CRUD 工具
  4. 04定义自定义工具、提示词和资源
  5. 05设置速率限制、配额和安全检查

适用场景

  1. 01在 Harper 上启用 MCP 端点
  2. 02选择某个 schema 对外提供的工具
  3. 03发布自定义内容和提示词模板
  4. 04加固公开的 MCP 端点

MCP 相关

指南说明 Harper 如何通过 Streamable HTTP 向客户端提供 MCP 工具、提示词和资源，并涵盖客户端握手、配置、访问控制及端点安全。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/harperfast/skills --skill harper-mcp

安装后在 Claude Code 中输入/harper-mcp确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

AGENTS.md
rules.manifest.yaml
rules/
automatic-verb-tools.md
connecting-clients.md
custom-mcp-prompts.md
custom-mcp-resources.md
custom-mcp-tools.md
durable-quotas.md
enabling-mcp.md
rate-limiting.md
resources-surface.md
security-posture.md

详细介绍

Harper MCP

关于如何将 Harper 实例作为模型上下文协议（MCP）服务公开，以及如何构建 AI 客户端使用的工具、提示词和资源的指南。Harper 实现了 MCP Streamable HTTP（规范修订版 2025-06-18），包含两个相互独立的配置文件：application（应用的接口）和 operations（Harper 管理）。

适用场景

在以下情况下，请参考这些指南：

  • 在 Harper 实例上启用或配置 MCP 端点
  • 将 MCP 客户端（Claude、Agent 框架、自定义 HTTP 代码）连接到 Harper
  • 决定 AI 应针对某个架构看到哪些工具，或精简其接口
  • 向 AI 客户端公开自定义行为（mcpTools）、提示词模板（mcpPrompts）或内容（mcpResources）
  • 保护公开或可匿名访问的 MCP 端点（速率限制、持久配额、加固）
  • 调试 MCP 线路错误（会话／协议标头、400 错误、SSE）

工作原理

  1. 先阅读 enabling-mcp，挂载配置文件，然后阅读 connecting-clients，了解握手约定。
  2. 对于工具接口，首先参考 automatic-verb-tools——大多数 CRUD 需求无需编写代码即可满足；只有确实需要自定义行为时才使用 custom-mcp-tools。
  3. 对于内容和模板，请使用 custom-mcp-resources 和 custom-mcp-prompts；resources-surface 则说明了无需编写代码即可使用的内容。
  4. 在公开提供服务之前，请完成 security-posture 检查清单，并配置 rate-limiting（对于产生费用的工具，还需配置 durable-quotas）。

示例

请参阅每条规则中包含的具体示例（curl 握手、static mcpTools／mcpResources 声明、配额钩子实现和加固配置）。

按优先级划分的规则类别

优先级类别影响前缀
1设置与连接高setup-
2工具与提示词高tools-
3资源中resources-
4运维与安全高ops-

快速参考

1. 设置与连接（高）
  • enabling-mcp — 如何启用和配置 Harper 的 MCP 服务配置文件（application 和 operations）。
  • connecting-clients — MCP 客户端如何连接到 Harper——包括初始化握手、会话和协议版本标头，以及身份验证。
2. 工具与提示词（高）
  • automatic-verb-tools — Harper 如何从导出的表自动生成 CRUD MCP 工具，包括 RBAC 筛选和 allow／deny／maxTools 控制。
  • custom-mcp-tools — 如何通过静态 mcpTools 将自定义实例方法公开为 MCP 工具，包括匿名公开的安全模型。
  • custom-mcp-prompts — 如何通过静态 mcpPrompts 向 MCP 客户端发布可复用的提示词模板。
3. 资源（中）
  • resources-surface — MCP 资源接口——harper:// 元数据 URI、harper+rest:// 表描述符、模板、订阅和 list_changed 通知。
  • custom-mcp-resources — 如何通过静态 mcpResources 将自定义内容（文档页面、报告、二进制文件）作为 MCP 资源提供，并使用 URI 模板和补全功能。
4. 运维与安全（高）
  • rate-limiting — MCP tools/call 速率限制——按工具、会话和客户端身份划分的令牌桶，以及 identityHeader 信任模型。
  • durable-quotas — 可由运维人员插拔的 MCP tools/call 持久配额，使用 server.setMcpQuotaHandler 注册钩子和防竞态计数器模式。
  • security-posture — MCP 安全模型——匿名访问、RBAC 边界、来源验证、审计日志，以及公开实例的加固检查清单。

使用方法

请阅读各条规则文件，了解详细说明和代码示例：

rules/enabling-mcp.md
rules/connecting-clients.md
rules/custom-mcp-tools.md
rules/custom-mcp-resources.md
rules/security-posture.md

完整编译文档

如需包含所有规则详情的完整指南，请参阅：AGENTS.md

评论

支持 Markdown