# mcp-esa-server-python

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) の下で公開されています。

## 使用している外部コード / Dependencies

このプロジェクトの一部では、以下のMIT Licenseで公開されているコードを参照しています。

- **esa-mcp-server**
  - GitHubリポジトリ: [https://github.com/masseater/esa-mcp-server]
  - ライセンス: MIT License

## その他 (Misc)

### 生成元 (Generated by)

generated by Cursor (gemini-2.5-pro-exp-03-25)