MCP Server (mcp-tools)

MCP サーバー（mcp-tools）

このプロジェクトには、Model Context Protocol（MCP）を使用して stdin/stdout 経由で通信し、AI エージェントにツールを提供するために設計された汎用 MCP サーバーが含まれています。

提供するツール

サーバーでは現在、call_tool エンドポイントから呼び出せる次のツールを提供しています。

check_markdown_link_file

• 説明： 指定された単一の Markdown ファイル内にある HTTP/HTTPS リンクをチェックします。
• 引数：
  • file_path（string、必須）：Markdown ファイルへのパス（プロジェクトのルートからの相対パス、または絶対パス）。
• arguments の例：

  {
    "file_path": "docs/usage.md"
  }
  

• 出力： ファイル内で見つかったリンクの状態（合計、有効、リンク切れ、エラー）を詳しく示すテキストレポート。

check_markdown_link_files

• 説明： 指定された Markdown ファイルのリスト内にある HTTP/HTTPS リンクをチェックします。
• 引数：
  • file_paths（文字列のリスト、必須）：Markdown ファイルへのパスのリスト（プロジェクトのルートからの相対パス、または絶対パス）。
• arguments の例：

  {
    "file_paths": [
      "README.md",
      "docs/requirements/link_checker_tool_enhancements_reqs.md"
    ]
  }
  

• 出力： 処理したすべてのファイルにわたるリンクの状態をまとめたテキストレポート。

check_markdown_link_directory

• 説明： 指定されたディレクトリを再帰的にスキャンして *.md ファイルを探し、その中にある HTTP/HTTPS リンクをチェックします。
• 引数：
  • directory_path（string、必須）：スキャンするディレクトリへのパス。
• arguments の例：

  {
    "directory_path": "docs/"
  }
  

• 出力： ディレクトリ内で見つかったすべての Markdown ファイルにわたるリンクの状態をまとめたテキストレポート。

check_markdown_links_project

• 説明： .gitignore ファイルで指定されたファイルを除外してプロジェクト全体をスキャンし、残りの *.md ファイル内にある HTTP/HTTPS リンクをチェックします。
• 引数： なし。
• arguments の例：

  {}
  

• 出力： プロジェクト内で見つかった処理対象のすべての Markdown ファイルにわたるリンクの状態をまとめたテキストレポート（.gitignore の設定を反映）。

セットアップと使用方法（Makefile を使用）

このプロジェクトでは、Makefile で実行を管理しながら、環境と依存関係の管理に uv を使用します。

1. プロジェクトディレクトリに移動します： このプロジェクト（mcp-server）のルートディレクトリにいることを確認してください。

   cd /path/to/mcp-server
   

2. 依存関係（開発・テスト用を含む）をインストールします： このコマンドは、ローカルの仮想環境（.venv）が存在しない場合は作成し、uv を使用して必要なパッケージをすべてインストールします。

   make install-dev
   

3. テストとカバレッジを実行します：

   make test
   

   このコマンドは、pytest を使用してすべてのユニットテストを実行し、coverage.py を使用してコードカバレッジレポートを生成します。

   • テスト実行では、カバレッジが合計で 85% を下回ると失敗する ように設定されています（Makefile を参照）。
   • 2025-04-04 時点のカバレッジ状況：
     • 全体：85%
     • src/mcp_server/server.py：81%（主要なハンドラーはカバー済み。main ループは未テスト）
     • src/mcp_server/tools/link_checker.py：89%（主要なロジックはカバー済み。一部のステータスチェックのエッジケースは未テスト）

4. コードのリントとフォーマット： ruff を使用してリントエラーをチェックし、プロジェクトの規約に従ってコードをフォーマットします。

   make lint
   

5. サーバーを実行します（手動）： サーバーは stdin/stdout で待ち受けます。

   make run
   

   (注：手動で対話するには、call_tool の前に initialize と initialized を含む、正しい形式の JSON-RPC メッセージを送信する必要があります。)

6. クリーンアップ： 仮想環境とキャッシュファイルを削除します。

   make clean
   

Cursor MCP Integration (Linux)

このサーバーは、~/.cursor/mcp.json に次のグローバル設定を記述することで、MCP ツールとして Cursor に統合できます（このファイル／ディレクトリを作成する必要がある場合があります）。

{
  "mcpServers": {
    "local-link-checker": {
      "name": "Local Link Checker", // Name displayed in Cursor
      "type": "command",
      // Use the absolute path to the python executable within THIS project's venv
      "command": "/absolute/path/to/mcp-server/.venv/bin/python",
      "args": [
        "-m", // Run module
        "mcp_server.server" // The server module to run
      ]
      // Optional: Define the working directory if needed (usually handled by -m)
      // "cwd": "/absolute/path/to/mcp-server"
    }
  }
}

統合に関する重要な注意事項：

• 絶対パス： /absolute/path/to/mcp-server を、お使いのシステム上にあるこのプロジェクトの正しい絶対パスに必ず置き換えてください。
• 仮想環境： この設定は、最初に make install-dev を実行して、このプロジェクトディレクトリ内に .venv を作成し、依存関係をインストールしていることを前提としています。
• 作業ディレクトリとファイルパス： python -m 経由で実行する場合、サーバーの作業ディレクトリは通常、プロジェクトのルート（/absolute/path/to/mcp-server）です。そのため、ツール（例：@Local Link Checker）を呼び出す際、file_path 引数にはこのプロジェクトルートからの相対パス（例：ルートにあるファイルの場合は file_path: test_links.md）または絶対パスを指定してください。
• Cursor の再起動： ~/.cursor/mcp.json を追加または変更した後、変更を反映するには Cursor を再起動する必要があります。

Cursor の Linux におけるプロセス実行環境の問題により、異なる方法（uv run やシェルラッパーなど）を使用した以前の統合は失敗しました。プロジェクト独自の仮想環境を使用して python -m で直接実行する方法が、動作することを確認済みの設定です。

新しいツールの追加

1. handle_list_tools（src/mcp_server/server.py）でツールのスキーマを定義します。
2. handle_call_tool（src/mcp_server/server.py）に、新しい elif name == "your-tool-name": ブロックを追加して、ツールのロジックを実装します。
   • 必要に応じて、ヘルパー関数を src/mcp_server/tools/ 内の別ファイルに作成します。
   • ヘルパー関数のユニットテストを tests/ に追加します。
3. 新しい依存関係があれば pyproject.toml に追加します。
4. 新しい テスト専用 の依存関係を追加する場合は、Makefile の install-dev ターゲットを更新します（基本の依存関係は install-dev 内の uv sync で処理されます）。
5. この README を更新します。

コントリビューション

コントリビューションを歓迎します！標準的なコーディング規約に従い、プルリクエストを送信する前にテスト（make test）が通ることを確認してください。

ライセンス

[ライセンスをここに指定してください]