Building a CSS Tutor MCP Server

CSS チューター MCP サーバーの構築

このリポジトリには、Node.js と TypeScript で構築されたシンプルな Model Context Protocol（MCP）サーバーが含まれています。「CSS チューター」として動作し、接続された AI クライアントに CSS 機能に関する最新情報をパーソナライズして提供します。

このサーバーでは、リソース、ツール、プロンプトの定義という主要な MCP の概念を紹介します。このデモの目的は、ここからさらに発展させ、より大規模で興味深いエージェント機能を構築できるようにすることです。

前提条件

• Node.js（v18 以降を推奨）
• npm（または yarn、pnpm など、お好みの Node.js パッケージマネージャー）
• MCP サーバーに接続できる AI クライアント（例：Claude デスクトップアプリ）
• OpenRouter API Key（Perplexity 経由で最新の CSS 情報を取得するため）

クイックスタート

次の手順で、サーバーをすばやく起動できます。

1. リポジトリをクローンします：

   git clone https://github.com/3mdistal/css-mcp-server.git
   cd css-mcp-server
   

2. 依存関係をインストールします：

   npm install # または: yarn install / pnpm install
   

3. API キーを準備します： get_latest_updates ツールには OpenRouter API キーが必要です。OpenRouter からキーを取得してください。このキーは手順 5 で MCP クライアントに渡します。

4. サーバーをビルドします： TypeScript コードをコンパイルします。

   npm run build # または: yarn build / pnpm run build
   

5. MCP クライアントを設定します： サーバーの起動方法をクライアントに伝え、環境変数として API キーも渡します。Claude デスクトップアプリの claude_desktop_config.json を使う場合の例を示します。

   {
     "mcpServers": {
       "css-tutor": {
         "command": "node",
         "args": [
           "/full/path/to/your/css-mcp-server/build/index.js"
         ],
         "env": {
           "OPENROUTER_API_KEY": "sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxx"
         }
       }
     }
   }
   

   （args 内のパスが、お使いのシステム上にあるビルド済み index.js ファイルの正しい絶対パスであることを確認してください。プレースホルダーの API キーを置き換えてください。）

6. 接続します： MCP クライアントから接続を開始します。クライアントが環境変数に API キーを設定した状態でサーバープロセスを起動し、操作を開始できます！

Cursor での使用

Cursor は AI を中心に設計されたコードエディターで、MCP クライアントとして動作できます。このサーバーを Cursor でセットアップするのは簡単ですが、ガイダンスプロンプトには追加の手順が必要です。

1. Cursor でサーバーを設定する：

   • Cursor Settings > MCP > Add new global MCP server の順に移動します。
   • Claude Desktop の手順で使用したものと同じ JSON を、同じ注意事項に従って貼り付けます。

2. プロンプト用の Cursor プロジェクトルールを作成する： 現在、Cursor はサーバーが提供する MCP プロンプトを自動的に使用しません。代わりに、Cursor の Project Rules 機能を使ってガイダンスを提供する必要があります。

   • プロジェクトのルートに .cursor/rules ディレクトリがない場合は作成します。

   • その中に css-tutor.rule という名前のファイルを作成します（または任意の .rule ファイル名を使用します）。

   • 次のガイダンステキストを css-tutor.rule に貼り付けます。

     You are a helpful assistant connecting to a CSS knowledge server. Your goal is to provide the user with personalized updates about new CSS features they haven't learned yet.
     
     Available Tools:
     1.  `get_latest_updates`: Fetches recent general news and articles about CSS. Use this first to see what's new.
     2.  `read_from_memory`: Checks which CSS concepts the user already knows based on their stored knowledge profile.
     3.  `write_to_memory`: Updates the user's knowledge profile. Use this when the user confirms they have learned or already know a specific CSS concept mentioned in an update.
     
     Workflow:
     1.  Call `get_latest_updates` to discover recent CSS developments.
     2.  Call `read_from_memory` to get the user's current known concepts (if any).
     3.  Compare the updates with the known concepts (if any). Identify 1-2 *new* concepts relevant to the user. **Important: They _must_ be from the response returned by `get_latest_updates` tool.**
     4.  Present these new concepts to the user, adding any context as needed, in addition to the information returned by the `get_latest_updates`.
     5.  Ask the user if they are familiar with these concepts or if they've learned them now.
     6.  If the user confirms knowledge of a concept, call `write_to_memory` to update their profile for that specific concept.
     7.  Focus on providing actionable, personalized learning updates.
     

3. 接続して使用する：

   • Cursor の MCP 設定で css-tutor サーバーが有効になっていることを確認します。
   • 新しいチャットまたはコード生成リクエスト（例：Cmd+K）を開始し、リクエストに @css-tutor-rule（またはルールファイルに付けた名前）を含めます。これにより Cursor はルールの内容を読み込み、接続された MCP サーバーが提供する read_from_memory、write_to_memory、get_latest_updates ツールの使い方に関する指示を適用します。

プロンプト／ルールがなくても、依頼すれば Cursor は個々のツールを使用できます。プロンプトは、ツールを呼び出してメモリを読み書きするためのワークフローと順序を提供します。

コードを理解する

このセクションでは、サーバーの実装について概要を説明します。

使用されている MCP の概念

• リソース（css_knowledge_memory）： ユーザーが把握している CSS の概念を表し、data/memory.json に永続的に保存されます。
• ツール： サーバーが実行できる操作です。
  • get_latest_updates：OpenRouter/Perplexity から CSS のニュースを取得します。
  • read_from_memory：css_knowledge_memory リソースの内容を読み取ります。
  • write_to_memory：css_knowledge_memory リソースを変更します。
• プロンプト（css-tutor-guidance）： ツールやリソースを効果的に利用する方法を AI クライアントに案内する静的な指示です。

コード構成

コードは次のように構成されています。

• data/memory.json：既知の CSS の概念を保存するデータベースとして機能するシンプルな JSON ファイルです。デフォルト版がリポジトリに含まれています。
• src/resources/index.ts：css_knowledge_memory リソースを定義します。次のものが含まれています。
  • データを検証するための Zod スキーマ。
  • ファイルの入出力を行う readMemory 関数と writeMemory 関数。
  • memory:// URI スキームと読み取り／書き込み権限を指定する server.resource による登録。読み取りハンドラーは data/memory.json の内容を返します。
• src/tools/index.ts：server.tool を使用して、次の 3 つのツールを定義します。
  • read_from_memory：readMemory を呼び出します。
  • write_to_memory：concept と known を入力として受け取り（スキーマは Zod で定義）、readMemory と writeMemory を使って JSON ファイルを更新します。
  • get_latest_updates：OPENROUTER_API_KEY が必要です。node-fetch と perplexity/sonar-pro モデルを使用して OpenRouter API を呼び出し、AI が生成した要約を返します。
• src/prompts/index.ts：server.prompt を使用して、静的な css-tutor-guidance プロンプトを定義します。プロンプトのテキストはコードに直接埋め込まれています。
• src/index.ts：メインサーバーのエントリポイントです。
  • @modelcontextprotocol/sdk から McpServer インスタンスを初期化します。
  • 他のモジュールから registerPrompts、registerResources、registerTools 関数をインポートして呼び出します。
  • StdioServerTransport を使って標準入出力経由の通信を処理します。
  • サーバーをトランスポートに接続し、基本的なエラー処理を行います。
• package.json：依存関係（@modelcontextprotocol/sdk、dotenv、node-fetch、zod）と build スクリプト（tsc）を定義します。
• .env.example / .env：OPENROUTER_API_KEY の保存に使用します（設定にオプション A を使用する場合）。
• .gitignore：node_modules、build、.env と、デフォルトの data/memory.json を除く data/ の内容を無視するよう設定されています。
• tsconfig.json：標準的な TypeScript 設定です。

MCP Inspector を使ったデバッグ

サーバーをデバッグしたり、やり取りされる生の JSON-RPC メッセージを確認したりする必要がある場合は、@modelcontextprotocol/inspector ツールを使用できます。このツールは基本的な MCP クライアントとして機能し、サーバーを起動して通信の流れを表示します。

プロジェクトのルートディレクトリでターミナルから Inspector を実行します。

npx @modelcontextprotocol/inspector node ./build/index.js

説明：

• npx @modelcontextprotocol/inspector：必要に応じて Inspector パッケージをダウンロードし、実行します。
• node：サーバーの実行に使用するコマンドです。
• ./build/index.js：コンパイル済みサーバーのエントリポイントへのパス（プロジェクトのルートディレクトリからの相対パス）です。

Inspector の環境変数：

Inspector はサーバーを子プロセスとして起動します。サーバーが環境変数（get_latest_updates ツール用の OPENROUTER_API_KEY など）に依存している場合は、npx コマンドを実行する環境でその変数を利用できるようにしてください。この状況では .env ファイルが自動的に読み込まれない場合があります。通常は、コマンドの前に次のように指定できます。

# Example on Linux/macOS
OPENROUTER_API_KEY="sk-or-xxxxxxxxxx" npx @modelcontextprotocol/inspector node ./build/index.js

# Example on Windows (Command Prompt)
set OPENROUTER_API_KEY=sk-or-xxxxxxxxxx && npx @modelcontextprotocol/inspector node ./build/index.js

# Example on Windows (PowerShell)
$env:OPENROUTER_API_KEY="sk-or-xxxxxxxxxx"; npx @modelcontextprotocol/inspector node ./build/index.js

sk-or-xxxxxxxxxx を実際のキーに置き換えてください。

まとめ

このデモでは、TypeScript SDK を使用して機能する MCP サーバーを作成する際の基本的な手順を紹介しました。状態を管理するリソース、アクションを実行するツール（外部 API との連携を含む）、AI クライアントを導くプロンプトを定義しました。

このデモが、これよりもはるかに複雑で便利なサーバーの構築方法を理解する助けになれば幸いです。

（また、🐛バグを見つけた場合は、気軽に issue を作成してください。）