THC Open Mindfulness MCP

THC Open Mindfulness MCP

一个公开、只读的 Model Context Protocol 服务，用于访问 The Holistic Care 批准的公开正念资源——互动游戏、免费引导式音频练习、通俗易懂的研究摘要、术语表、公开的 PanchaVikas 框架概览，以及 The Holistic Care Podcast 的剧集（英语和印地语）。

• 生产环境端点： https://mcp.theholisticcare.com/mcp（Streamable HTTP）
• 无需身份验证。 不需要 API 密钥，不需要 OAuth，也无需注册。
• 只读。 此服务中的工具不会创建、修改或删除任何内容。
• 完全由公开 REST API 提供支持——api.theholisticcare.com（文档，源代码）。此服务绝不会直接连接到 Sanity CMS、数据库或任何支付系统。

目录

• 为何创建此服务
• 架构
• 工具
• 资源
• 通过 MCP 客户端使用
• 本地开发
• 使用 MCP Inspector 进行测试
• 部署
• 安全性
• 许可
• 贡献 / 问题反馈

为何创建此服务

The Holistic Care 已经通过公开 REST API 发布其正念内容。此服务是对该 API 的轻量 MCP 封装，让任何兼容 MCP 的客户端（Claude Desktop、Claude Code、自定义 Agent 等）都能通过原生工具调用发现和使用这些内容，而无需专门集成 HTTP；同时遵循 REST API 本身已有的内容边界。

架构

MCP client (Claude, etc.)
        │  Streamable HTTP, JSON-RPC
        ▼
 thc-mindfulness-mcp  (this repo — Next.js App Router, deployed to Vercel)
        │  plain HTTPS GET, no credentials
        ▼
 api.theholisticcare.com  (sibling REST API project)
        │
        ▼
 Sanity CMS (never touched directly by this server)

• 运行时： Vercel 上的 Next.js（App Router），Node.js 运行时（非 Edge——MCP SDK 需要 Node API）。
• MCP SDK： @modelcontextprotocol/server v2（createMcpHandler、McpServer），现代化的高级软件包。@modelcontextprotocol/sdk v1 仅作为开发依赖保留，用于较低级别的类型定义和未来的进程内测试客户端。
• 传输方式： 无状态 Streamable HTTP。每个请求都会创建一个全新的 McpServer 实例（src/server.ts）——没有会话存储，因此一个调用方的请求不会泄漏给其他调用方。
• 验证： 使用 Zod v4 schema 验证每个工具输入（src/schemas.ts）；无论 SDK 本身已执行何种检查，服务端都会重新验证。
• 内容边界： 完全通过此服务对上游 REST API 调用的端点来强制执行（src/lib/apiClient.ts、src/lib/constants.ts）。基础 URL 是编译时常量；任何工具参数都无法更改此服务连接的主机。

工具

所有 8 个工具均为只读，不会执行破坏性操作（每个工具的注释中均为 readOnlyHint: true、destructiveHint: false），并返回少量（默认 6 个，最多 20 个）规范化资源，而非批量转储。

工具	功能	数据来源
search_mindfulness_resources	同时在所有公开资源类别（博客、游戏、练习、研究、术语表、PanchaVikas、播客剧集）中进行全文搜索，可选用 resource_type/category/audience/skill/age 筛选。	GET /v1/search，在客户端筛选
get_mindfulness_resource	根据类型和标识符获取一项特定资源（大多数类别使用 slug，PanchaVikas 和播客剧集使用稳定 ID，例如 PC-S02E03-EN）。	对应的专用详情端点，例如 GET /v1/mindfulness-games/{slug}
find_mindfulness_games	查找互动式正念游戏，可按年龄、技能、受众和最长时长筛选。	GET /v1/mindfulness-games 或 GET /v1/search
find_guided_practices	查找 Stillness Library 中免费的引导式音频练习（绝不包含付费音轨）。	GET /v1/practices 或 GET /v1/search
search_mindfulness_research	搜索通俗易懂的研究摘要，可按主题和研究类型筛选。	GET /v1/whitepapers 或 GET /v1/search
lookup_mindfulness_term	根据名称查找一个术语表词条，可选用支柱筛选。	GET /v1/glossary/{slug}，失败时回退到搜索
find_panchavikas_resources	查找公开的 PanchaVikas 资源（框架路径和公开可下载指南，不包含私人课程内容）。	GET /v1/panchavikas/resources，在客户端筛选
find_podcast_episodes	查找 The Holistic Care Podcast 的剧集，可按 language（en/hi）、season 和自由文本 query 筛选。返回摘要、时长、发布日期、剧集页面和视频链接，绝不返回文字稿。	GET /v1/podcast/episodes，在客户端匹配查询

所有返回列表的工具都使用相同的输出结构 { results: Resource[], count: number }；get_mindfulness_resource 和 lookup_mindfulness_term 则返回 { found: boolean, resource: Resource | null }。每个工具的确切 Zod 输入架构，以及说明其无法完全准确应用哪些筛选条件的代码注释，请参阅 src/tools/ 下各工具对应的文件（会记录这些限制，不会静默忽略；详情请见下文关于 /v1/search 参数集较窄的说明）。

**已知且有文档记录的限制：**上游 /v1/search 端点仅接受 q/limit/offset，而 /v1/resources 和各类别的专用端点支持更丰富的筛选条件（category、audience、skill、age_min/age_max），但不支持自由文本查询。如果某个工具既需要自由文本搜索，又需要 /v1/search 不支持在服务端应用的筛选条件，它会从 /v1/search 获取更多结果，然后在客户端应用筛选条件（见 src/lib/filters.ts）。受影响工具的描述文本会明确说明这一点，让 MCP 客户端（及使用它的人）了解筛选条件确实有效，但实际是在事后应用，而非由上游 API 本身保证。

资源

五个静态信息型 MCP 资源——它们都不会调用上游 API，因此即使 api.theholisticcare.com 暂时不可用，也始终可用：

URI	内容
thc://about	介绍此服务的性质、提供方，以及指向底层 API/来源的链接。
thc://taxonomy	此服务可返回的资源类型，以及每种类型的含义。
thc://usage	合理使用说明：无需身份验证、尽力保证可用性、优先使用 source_url/canonical_url，并保持结果大小适中。
thc://content-rights	软件与内容的许可区分（MIT 代码，内容保留所有权利）——详见下文的许可。
thc://panchavikas/framework	公开的 PanchaVikas 五元素框架概述，并明确说明其有意排除的内容（私有课程）。

此服务没有 MCP 提示词，这是有意为之——本项目的规范明确避免仅仅因为协议支持提示词就添加提示词；这里没有需要提示词的内容。

在 MCP 客户端中使用

任何支持 Streamable-HTTP 的 MCP 客户端都可以直接连接到生产环境 URL。对于类似 claude_desktop_config.json 的远程 MCP 配置项：

{
  "mcpServers": {
    "thc-open-mindfulness": {
      "url": "https://mcp.theholisticcare.com/mcp"
    }
  }
}

客户端无需配置请求头、令牌或环境变量。

本地开发

npm install
npm run dev

随后，MCP 端点可通过 http://localhost:3000/mcp 访问，健康检查端点为 http://localhost:3000/health。

本地开发无需任何密钥。此服务读取的唯一环境变量是 THC_API_BASE_URL（参见 .env.example）；如果未设置，则默认使用生产环境 REST API——仅当需要将本地实例指向其他 API 时才设置它（例如，指向本地运行的 thc-open-mindfulness-api 副本）。

npm run typecheck   # tsc --noEmit
npm run lint        # next lint
npm run test        # unit tests (mocked fetch, no network)
npm run test:contract  # MCP protocol-level tests, in-process

使用 MCP Inspector 测试

MCP Inspector 是用于交互式测试 MCP 服务工具和资源的参考工具。

npx @modelcontextprotocol/inspector

然后连接到以下任一地址：

• http://localhost:3000/mcp（本地 npm run dev 实例），或
• https://mcp.theholisticcare.com/mcp（生产环境）

使用“Streamable HTTP”传输选项，且无需身份验证。你应该会看到列出的全部 8 个工具和 5 个资源，并可以逐一交互调用。

部署

本项目作为标准的 Next.js App Router 应用部署到 Vercel。

1. 将 GitHub 仓库导入一个新的 Vercel 项目。
2. 生产环境部署无需设置环境变量（THC_API_BASE_URL 默认为 https://api.theholisticcare.com）。
3. 将自定义域名 mcp.theholisticcare.com 指向 Vercel 项目（Vercel 控制台 → Domains），并在 theholisticcare.com 的 DNS 服务商处添加相应的 DNS 记录。
4. 部署后，验证：
   • https://mcp.theholisticcare.com/health 返回 {"status":"ok",...}
   • https://mcp.theholisticcare.com/mcp 能正确响应 MCP Inspector 会话（见上文）
   • npm run smoke:production 通过（scripts/smoke-production.mts——端到端测试线上端点）

安全

完整说明请参阅 SECURITY.md。简而言之：没有密钥、没有写入操作、不直接访问 Sanity/数据库、出站请求已加固以防 SSRF、HTTP 传输会验证 Host/Origin 请求头，并采用无状态请求模型。请将漏洞报告发送至 [email protected]，而不要创建公开问题。

许可

完整说明请参阅 LICENSING.md。简而言之：本仓库中的代码采用 MIT 许可；它检索并返回的正念内容（游戏、练习、研究摘要、术语表条目、博客摘录、PanchaVikas 概览）版权归 The Holistic Care 所有，© The Holistic Care，保留所有权利，除非特定资源另有说明——这些内容可公开阅读和引用，但不得整体再分发。另请参阅 ATTRIBUTION.md，了解如何在基于此服务构建内容时注明 The Holistic Care。

贡献 / 问题反馈

这是一个小型单用途服务，与 The Holistic Care 的公共 API 和网站一同维护。欢迎通过 GitHub Issues 提交错误报告和拉取请求。有关安全问题，请参阅 SECURITY.md，不要公开提交问题。