mcp-server

プロジェクト

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) を使用したり、未使用のコードをコメントアウトしたりしないでください。

一般的な未使用コード

• 対応: 現在使用されていない、または直ちに使用する予定のないコードは削除してください。
• 理由: コードベースをクリーンで焦点の合った状態に保ちます。