THC Open Mindfulness MCP

THC オープンマインドフルネス MCP

The Holistic Careが承認した公開マインドフルネスリソース（インタラクティブゲーム、無料のガイド付き音声プラクティス、わかりやすい研究概要、用語集、公開されているPanchaVikasフレームワークの概要、The Holistic Care Podcastのエピソード（英語とヒンディー語））を提供する、一般公開の読み取り専用Model Context Protocolサーバーです。

• 本番エンドポイント： 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、カスタムエージェントなど）は、独自の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スキーマ（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	種類と識別子を指定して、特定のリソースを1件取得します（ほとんどのリソース群ではスラッグ、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	任意の柱で絞り込みながら、用語名を指定して用語集の用語を1件検索します。	GET /v1/glossary/{slug}。見つからない場合は検索にフォールバック
find_panchavikas_resources	公開されているPanchaVikasのリソース（フレームワークの学習経路と、一般公開されているダウンロード可能なガイドのみ。非公開のカリキュラムは対象外）を検索します。	GET /v1/panchavikas/resources。クライアント側でフィルタリング
find_podcast_episodes	言語（en／hi）、シーズン、フリーテキストのqueryで絞り込み可能なThe Holistic Care Podcastのエピソードを検索します。概要、長さ、公開日、エピソードページ、動画リンクを返します。トランスクリプトは対象外です。	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 リソースが 5 つあります。いずれも上流 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 ヘッダー検証、ステートレスなリクエストモデルを採用しています。脆弱性は公開の Issue を作成するのではなく、[email protected] まで報告してください。

ライセンス

詳しくはLICENSING.mdをご覧ください。要約すると、このリポジトリのコードはMIT ライセンスの下で公開されています。一方、取得して返すマインドフルネスコンテンツ（ゲーム、実践方法、研究の要約、用語集の項目、ブログの抜粋、PanchaVikas の概要）は、個別のリソースに別段の記載がない限り、Copyright © The Holistic Care、無断転載禁止です。閲覧や参照はできますが、全体を再配布することはできません。このサーバーを基に構築する際の The Holistic Care のクレジット表記方法については、ATTRIBUTION.mdもご覧ください。

コントリビューション／問題の報告

これは、The Holistic Care の公開 API およびウェブサイトと並行して保守されている、小規模な単一目的のサーバーです。GitHub Issuesから、バグ報告やプルリクエストを歓迎します。セキュリティに関する問題については、公開の Issue を作成せず、SECURITY.mdをご覧ください。