feat: 🎸 initial commit for mcp esa server

Author: scnsh

.cursor/rules/mcp-server.mdc

@@ -0,0 +1,85 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# プロジェクト
+
+esa.ioのAPIを使用して、基本的な操作を行えるMCPサーバーを作る
+.envで完了変数を管理し、ESA_TOKEN, ESA_TEAM_NAMEでそれぞれAPIトークンとチーム名を管理する。
+
+esa.ioのAPIについては <https://docs.esa.io/posts/102> を参照。
+
+# 使用技術
+
+* python
+* uv
+
+# 開発計画
+
+1.  **基盤構築フェーズ**
+    * Pythonプロジェクト初期化 (`uv init`)
+    * 環境変数設定 (`.env`)
+    * APIクライアント基礎 (認証、ベースURL)
+
+2.  **コア機能実装フェーズ**
+    * **ユーザー情報取得 (`/user`, テスト)**
+    * 記事一覧取得 (`/posts`, 検索、テスト)
+    * 記事詳細取得 (`/posts/:post_number`, テスト)
+    * エラー処理
+
+3.  **追加機能と改善フェーズ**
+    * 記事作成 (`POST /posts`, テスト)
+    * 記事更新 (`PATCH /posts/:post_number`, テスト)
+    * 記事削除 (`DELETE /posts/:post_number`, テスト)
+
+4.  **ドキュメント整理**
+    * ドキュメント作成 (`docs/`)
+
+# 進め方のポイント
+
+* フェーズごとに `git commit`
+* TDD (テスト駆動開発)
+* **コードを修正したらテスト (`pytest`) とフォーマット/リントチェック (`ruff format`, `ruff check`) を実行する**
+* 必要に応じて機能追加 (コメント等)
+* サーバーのドキュメント作成
+
+# FastMCPツールでのロギング
+
+* **注意:** MCPツールの `main` 関数内でのロギングに `print` を使用しないでください。
+* **推奨:** 常に `logging` パッケージを使用してください。
+* `print` はpytestのコードでのみ使用してください。
+* 必要に応じて `logger.info()`、`logger.warn()`、`logger.error()`、`logger.debug()` を使用してください。
+
+# FastMCPサーバー開発ノート
+
+* MCPサーバーのコード (`main.py` またはその依存関係) を変更 (ツールの追加/削除、サーバー設定の変更) した後は、CursorでMCPサーバー情報を **再読み込み** する必要があります。
+* ツールを追加した直後に「見つからない」と表示される場合は、CursorでMCPサーバー接続を再読み込みしてみてください。
+* 変更が完全に認識されるまでに、複数回の再読み込みが必要になる場合があります。
+
+## 環境変数とインポート
+
+* モジュールのインポート時に即座に実行されるコード (例: `src/esa_client.py` のトップレベルでの環境変数チェック) には注意してください。
+* サーバーを起動する前に、必要な環境変数 (`ESA_TOKEN`, `ESA_TEAM_NAME`) が正しく設定されていること (例: `.env` と `dotenv` 経由で) を確認してください。
+
+## その他の注意点 (必要に応じて追記)
+
+# リント/フォーマットエラーを優先対応
+
+リンターやフォーマッターのエラーが発生した場合は、直ちに修正してください。これらのエラーが解決されるまで、他のタスクに進ないでください。
+
+# 定期的なフォーマットとリントチェック
+
+コードの品質と一貫性を確保するために、定期的に `ruff format && ruff check` を実行することを忘れないでください。
+
+# 追加タスク (Geminiによる)
+
+## `no-unused-vars` (未使用の変数)
+
+* **対応:** 未使用のインポートや変数は完全に削除してください。
+* **禁止:** アンダースコアプレフィックス (例: `_variable`) を使用したり、未使用のコードをコメントアウトしたりしないでください。
+
+## 一般的な未使用コード
+
+* **対応:** 現在使用されていない、または直ちに使用する予定のないコードは削除してください。
+* **理由:** コードベースをクリーンで焦点の合った状態に保ちます。

.env.example

@@ -0,0 +1,2 @@
+ESA_TEAM_NAME="YOUR_ESA_TEAM_NAME" # Replace with your esa.io team name (e.g., "myteam")
+ESA_TOKEN="YOUR_ESA_API_TOKEN"     # Replace with your esa.io API access token

.python-version

@@ -0,0 +1 @@
+3.13

README.md

@@ -1,2 +1,119 @@
 # mcp-esa-server-python
-esa.io の mcp server 
+
+esa.io API と連携するための Model Context Protocol Server (mcp server)です。Pythonで実装しています。
+
+## できること
+
+現在は以下の機能を提供しています。
+
+- ユーザー情報取得（user_get_info）
+- 記事一覧取得（posts_get_list）
+- 記事詳細取得（posts_get_detail）
+- 記事作成 (posts_create)
+- 記事更新 (posts_update)
+- 記事削除 (posts_delete)
+
+## セットアップ手順
+
+### 前提条件
+- esa.ioのAPIトークンを発行済であること
+- uv が使えること
+- インターネット接続
+
+- esa.ioのAPIトークンの発行方法
+    - あなたの esa.io チームのページにアクセスします (例: `https://<your-team-name>.esa.io/`)。
+    - 左カラムのSETTINGSをクリックし、「ユーザー設定」>「外部アプリ連携」を選択します。
+    - 「Personal access tokens」セクションで、「Generate new token」をクリックします。
+    - トークン名 (例: `mcp-server`) を入力し、必要な権限スコープを選択します。この MCP サーバーには少なくとも以下の権限が必要です:
+        - `read` (記事の読み取り)
+        - `write` (記事の作成・更新・削除)
+        - `read_user` (ユーザー情報の取得) （この項目は自動的に有効になるため、表示されない可能性があります）
+    - 「Save」をクリックします。
+    - **表示されたトークンを必ずコピーして安全な場所に保管してください。このトークンは一度しか表示されません。**
+    - コピーしたトークンは、後述の `.env` ファイルの `ESA_TOKEN` の値として貼り付けます。
+- [esa.io](https://esa.io/) では、サインアップから2ヶ月間の無料トライアル期間が提供されています。この期間を利用して、テスト用のチーム名とAPIトークンを取得することができます。
+- セキュリティのため、トークンは直接公開しないようご注意ください。
+
+
+### プロジェクトの初期化
+
+```bash
+uv sync
+```
+
+### 開発(ローカルでの使い方)
+
+開発に参加する場合や、MCPInspectorを利用する場合は、以下の手順で環境を構築します。
+
+1. 環境変数の設定
+    `.env.example` を参考にして、`.env` をサーバーを実行したいディレクトリ(`.env.example`と同じ場所)を作成します。
+    ```dotenv
+    ESA_TEAM_NAME="YOUR_ESA_TEAM_NAME" # Replace with your esa.io team name (e.g., "myteam")
+    ESA_TOKEN="YOUR_ESA_API_TOKEN"     # Replace with your esa.io API access token
+    ```
+
+2. 実行方法
+    下記コマンドを実行後に、指示のあるURLからブラウザを開くことで、MCP Inspectorを使って、各コマンド(記事作成など)を実行することができます。
+    ```bash
+    uv run mcp run main.py
+    ```
+
+### MCPServerとしてCursorエディタで使う方法
+
+1. **mcp.jsonの作成例**
+
+プロジェクトルートまたは `~/.cursor/mcp.json` に以下のような設定ファイルを用意します。
+
+```json
+{
+  "mcpServers": {
+    "mcp-esa-server": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "<プロジェクトの絶対パス>",
+        "run",
+        "main.py"
+      ],
+      "env": {
+        "ESA_TEAM_NAME": "<your-team-name>",
+        "ESA_TOKEN": "<your-esa-token>"
+      }
+    }
+  }
+}
+```
+- `<your-team-name>` と `<your-esa-token>` は各自のesa.ioチーム名・APIトークンに置き換えてください。
+- `env`: 環境変数を **直接** 設定します。**この方法を使用する場合、`.cursor/mcp.json` のコミットは絶対に避けてください。**
+
+
+2. **CursorエディタでMCPサーバーを起動**
+
+- CursorエディタのコマンドパレットやUIから「MCPサーバーを起動」または「AIツールを有効化」します。
+- mcp.jsonの設定に従い、`uv run main.py` でサーバーが起動します。
+- `.env` ファイルや環境変数も自動的に読み込まれます。
+
+3. **AIチャットやツールパネルからAPIを呼び出し**
+
+- AIチャット上で `user_get_info` や `posts_get_list` などのMCPツールを呼び出すことで、esa.io APIと連携した操作が可能です。
+- `mcp-esa-server  を使って記事の作成をお願いします` などとチャット上で書き込むことで利用できます。
+
+## ライセンス (License)
+
+このプロジェクトは [MIT License](./LICENSE) の下で公開されています。
+(注: `LICENSE` ファイルがまだリポジトリにない場合は、別途追加する必要があります。)
+
+## 使用している外部コード / Dependencies
+
+このプロジェクトの一部では、以下のMIT Licenseで公開されているコードを参照しています。
+
+- **[参照元プロジェクト名]**
+  - GitHubリポジトリ: [https://github.com/masseater/esa-mcp-server]
+  - ライセンス: MIT License
+
+## その他 (Misc)
+
+### 生成元 (Generated by)
+
+generated by Cursor (gemini-2.5-pro-exp-03-25)
+

docs/api_client_spec.md

@@ -0,0 +1,84 @@
+# MCPサーバー esa.io APIクライアント仕様
+
+このドキュメントは、esa.io API クライアント（EsaClientクラス）の実装仕様とテスト方針を記述します。
+
+## 1. 目的
+
+esa.io API との通信を行うための基本的なクライアント機能を提供します。認証情報の管理、リクエストの送信、基本的なエンドポイントへのアクセス機能を含みます。
+
+## 2. クライアント仕様
+
+- .envからESA_TOKEN/ESA_TEAM_NAMEを取得
+- requests.Sessionによる認証付き通信
+- get_user, get_posts, get_postメソッドを提供
+- エラー時は例外送出・ログ出力
+
+### 2.1. EsaClient クラス
+
+- 初期化時にdotenv.load_dotenv()で環境変数を取得し、認証情報を検証
+- APIベースURL（https://api.esa.io/v1/teams/{team_name}）を構築
+- 共通ヘッダー（Authorization, Content-Type）を設定
+- _requestヘルパーでAPIリクエストを共通化
+- get_user: 認証ユーザー情報取得
+- get_posts: 記事一覧取得（q, page, per_page対応）
+- get_post: 記事詳細取得（post_number指定）
+
+## 3. テスト方針・構成
+
+- pytestによるユニットテスト・インテグレーションテスト
+- モックによる外部依存排除
+- テストディレクトリ・マーカーの使い分け
+
+### 3.1. テスト構成
+- **ユニットテスト:**
+    - APIクライアントやMCPツールのロジックをモックで高速に検証します。
+    - テストファイル例: `tests/test_esa_client.py`, `tests/test_main_tools.py`
+- **インテグレーションテスト:**
+    - 実際のesa.io APIと通信し、全体の連携を検証します（.envとネットワークが必要）。
+    - テストファイル例: `tests/integration/test_esa_client_integration.py`
+- テストディレクトリは `tests/` 配下にあり、`integration/` サブディレクトリでインテグレーションテストを分離しています。
+- pytestのマーカー（`@pytest.mark.integration`）でインテグレーションテストを区別しています。
+
+### 3.2. ユニットテスト詳細
+- 主なテストファイル:
+    - `tests/test_esa_client.py`: EsaClientクラスの初期化・APIメソッドの正常系/異常系
+    - `tests/test_main_tools.py`: MCPツールの引数処理・EsaClient呼び出し・エラーハンドリング
+- モック・フィクスチャ:
+    - `monkeypatch` で環境変数をセット
+    - `unittest.mock.patch` で requests や EsaClient のメソッドをモック
+- 主なテストケース例:
+    - 認証情報がない場合の初期化エラー
+    - get_user の正常/エラー応答
+    - get_posts のパラメータ有無・エラー応答
+    - MCPツールが正しいEsaClientメソッドを呼ぶか
+
+### 3.3. インテグレーションテスト詳細
+- 主なテストファイル:
+    - `tests/integration/test_esa_client_integration.py`
+- 内容:
+    - 実際のesa.io APIと通信し、ユーザー情報・記事一覧・記事詳細の取得を検証
+    - 存在しない記事番号で404エラーを検証
+- 注意点:
+    - `.env`ファイルに有効なESA_TOKEN/ESA_TEAM_NAMEが必要
+    - ネットワーク接続が必要
+    - 実行に時間がかかる場合あり
+
+## 4. テスト実行方法
+
+- **ユニットテストのみ実行:**
+    ```bash
+    uv run pytest tests/
+    ```
+- **インテグレーションテストのみ実行:**
+    ```bash
+    uv run pytest -m integration tests/integration/
+    ```
+- **全テスト実行:**
+    ```bash
+    uv run pytest
+    ```
+
+---
+
+※サーバー全体の設計・開発まとめは docs/20250504/mcp_esa_development_summary.md を参照。
+※利用方法・MCPツールの説明は docs/mcp_esa_server_usage.md を参照。

docs/mcp_esa_development_summary.md

@@ -0,0 +1,42 @@
+# esa.io MCPサーバー開発まとめ
+
+## 概要
+
+本プロジェクトは、esa.ioのAPIをAIアシスタントから操作できるMCPサーバーの開発を目的としています。
+
+## サーバー設計・技術スタック
+
+- **FastAPI**: Webフレームワーク
+- **FastMCP**: MCPプロトコル実装
+- **aiohttp**: 非同期HTTPクライアント
+- **pytest/ruff**: テスト・フォーマット
+
+## 主要機能
+
+- ユーザー情報取得（user_get_info）
+- 記事一覧取得（posts_get_list）
+- 記事詳細取得（posts_get_detail）
+- 記事作成 (posts_create)
+- 記事更新 (posts_update)
+- 記事削除 (posts_delete)
+
+## 実装ポイント
+
+- MCPツールとしてユーザー情報・記事一覧・記事詳細取得を実装
+- 環境変数・エラーハンドリングの徹底
+- ユニットテスト・インテグレーションテストの分離
+
+## 技術的課題と解決策
+- .envによる安全な認証情報管理
+- テストのモック化・テスト対応
+
+## 今後の課題
+
+- 他のAPI操作の実装
+- エラーハンドリングの強化
+- テスト拡充・パフォーマンス最適化
+
+---
+
+※APIクライアントの詳細仕様・テスト構成は docs/api_client_spec.md を参照。
+※利用方法・起動手順・MCPツールの説明は docs/mcp_esa_server_usage.md を参照。