harper-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Harper MCP

Guidelines for exposing a Harper instance as a Model Context Protocol (MCP) server and for building the tools, prompts, and resources AI clients consume. Harper implements MCP Streamable HTTP (spec rev 2025-06-18) with two independent profiles:

application

(your app's surface) and

operations

(Harper administration).

本指南介绍如何将Harper实例部署为Model Context Protocol（MCP）服务器，以及构建AI客户端所需的工具、提示词和资源。Harper实现了MCP Streamable HTTP（规范版本2025-06-18），包含两个独立配置文件：

application

（应用层面）和

operations

（Harper管理层面）。

When to Use

使用场景

Reference these guidelines when:

Enabling or configuring the MCP endpoint on a Harper instance
Connecting an MCP client (Claude, agent frameworks, custom HTTP code) to Harper
Deciding what tools an AI should see for a schema, or trimming that surface
Exposing custom behavior (
```
mcpTools
```
), prompt templates (
```
mcpPrompts
```
), or content (
```
mcpResources
```
) to AI clients
Protecting a public or anonymous-accessible MCP endpoint (rate limits, durable quotas, hardening)
Debugging MCP wire errors (session/protocol headers, 400s, SSE)

在以下场景中参考本指南：

在Harper实例上启用或配置MCP端点
将MCP客户端（Claude、Agent框架、自定义HTTP代码）连接到Harper
确定AI针对某一模式应可见的工具，或精简工具范围
向AI客户端暴露自定义行为（
```
mcpTools
```
）、提示词模板（
```
mcpPrompts
```
）或内容（
```
mcpResources
```
）
保护公开或可匿名访问的MCP端点（速率限制、持久配额、加固）
调试MCP通信错误（会话/协议头、400状态码、SSE）

How It Works

工作原理

Start with
```
enabling-mcp
```
to mount a profile, then
```
connecting-clients
```
for the handshake contract.
For the tool surface, consult
```
automatic-verb-tools
```
first — most CRUD needs are covered with zero code — and reach for
```
custom-mcp-tools
```
only for real behavior.
For content and templates, use
```
custom-mcp-resources
```
and
```
custom-mcp-prompts
```
;
```
resources-surface
```
explains what exists without any code.
Before any public exposure, work through
```
security-posture
```
's checklist and configure
```
rate-limiting
```
(+
```
durable-quotas
```
for cost-bearing tools).

首先通过
```
enabling-mcp
```
挂载配置文件，然后通过
```
connecting-clients
```
完成握手协议。
对于工具范围，首先参考
```
automatic-verb-tools
```
——大多数CRUD需求无需代码即可满足——仅在需要实现实际行为时使用
```
custom-mcp-tools
```
。
对于内容和模板，使用
```
custom-mcp-resources
```
和
```
custom-mcp-prompts
```
；
```
resources-surface
```
介绍了无需代码即可使用的现有资源。
在公开暴露之前，完成
```
security-posture
```
的检查清单，并配置
```
rate-limiting
```
（对于产生成本的工具，还需配置
```
durable-quotas
```
）。

Examples

示例

See the concrete examples embedded in each rule (curl handshakes,

static mcpTools

mcpResources

declarations, quota-hook implementations, and hardening configs).

查看每个规则中嵌入的具体示例（curl握手、

static mcpTools

mcpResources

声明、配额钩子实现以及加固配置）。

Rule Categories by Priority

按优先级划分的规则类别

Priority	Category	Impact	Prefix
1	Setup & Connection	HIGH	`setup-`
2	Tools & Prompts	HIGH	`tools-`
3	Resources	MEDIUM	`resources-`
4	Operations & Security	HIGH	`ops-`

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

Quick Reference

快速参考

1. Setup & Connection (HIGH)

1. 设置与连接（高优先级）

```
enabling-mcp
```
— How to enable and configure Harper's MCP server profiles (application and operations).
```
connecting-clients
```
— How MCP clients connect to Harper - the initialize handshake, session and protocol-version headers, and authentication.

```
enabling-mcp
```
— 如何启用和配置Harper的MCP服务器配置文件（应用和运维层面）。
```
connecting-clients
```
— MCP客户端如何连接到Harper——初始化握手、会话和协议版本头，以及身份验证。

2. Tools & Prompts (HIGH)

2. 工具与提示词（高优先级）

```
automatic-verb-tools
```
— How Harper auto-generates CRUD MCP tools from exported tables, with RBAC filtering and allow/deny/maxTools controls.
```
custom-mcp-tools
```
— How to expose custom instance methods as MCP tools via static mcpTools, including the anonymous-exposure security model.
```
custom-mcp-prompts
```
— How to publish reusable prompt templates to MCP clients via static mcpPrompts.

```
automatic-verb-tools
```
— Harper如何从导出的表自动生成CRUD MCP工具，包含RBAC过滤以及允许/拒绝/maxTools控制。
```
custom-mcp-tools
```
— 如何通过static mcpTools将自定义实例方法暴露为MCP工具，包括匿名访问的安全模型。
```
custom-mcp-prompts
```
— 如何通过static mcpPrompts向MCP客户端发布可复用的提示词模板。

3. Resources (MEDIUM)

3. 资源（中优先级）

```
resources-surface
```
— The MCP resources surface - harper:// metadata URIs, harper+rest:// table descriptors, templates, subscriptions, and list_changed notifications.
```
custom-mcp-resources
```
— How to serve custom content (docs pages, reports, binaries) as MCP resources via static mcpResources with URI templates and completions.

```
resources-surface
```
— MCP资源范围——harper://元数据URI、harper+rest://表描述符、模板、订阅以及list_changed通知。
```
custom-mcp-resources
```
— 如何通过带有URI模板和补全功能的static mcpResources，将自定义内容（文档页面、报告、二进制文件）作为MCP资源提供。

4. Operations & Security (HIGH)

4. 运维与安全（高优先级）

```
rate-limiting
```
— MCP tools/call rate limiting - per-tool, per-session, and per-client-identity token buckets, and the identityHeader trust model.
```
durable-quotas
```
— Operator-pluggable durable quotas for MCP tools/call via the server.setMcpQuotaHandler registration hook, with a race-safe counter pattern.
```
security-posture
```
— The MCP security model - anonymous access, RBAC boundaries, origin validation, audit logging, and the hardening checklist for public instances.

```
rate-limiting
```
— MCP工具/调用速率限制——按工具、按会话、按客户端身份的令牌桶机制，以及identityHeader信任模型。
```
durable-quotas
```
— 运维人员可通过server.setMcpQuotaHandler注册钩子为MCP工具/调用配置可插拔的持久配额，包含竞态安全的计数器模式。
```
security-posture
```
— MCP安全模型——匿名访问、RBAC边界、来源验证、审计日志，以及公开实例的加固检查清单。

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

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

阅读单个规则文件以获取详细说明和代码示例：

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

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需包含所有扩展规则的完整指南，请查看：

AGENTS.md