> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shanone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ツールリファレンス

> emma MCP Serverの全ツールの完全なリファレンスドキュメント。パラメータ、例、戻り値を含みます。

このページでは、emma MCP Serverで利用可能な9つのツールすべての詳細なドキュメントを提供します。全ツールはプレーンテキスト（Markdown整形）を返します。構造化されたJSONは返しません — 以下の例は、そのテキストの形式を示しています。

## ヘルスチェック

### emma\_health\_check

emma MCPサーバーの接続状態と認証状態を確認します。他のツールを実行する前にAPIキーが有効であることを確認するために使用します。パラメータはありません。

<Tabs>
  <Tab title="リクエスト例">
    ```json theme={null}
    {}
    ```
  </Tab>

  <Tab title="レスポンス例">
    ```
    Emma Remote MCP Server: healthy. API key is valid.
    ```
  </Tab>
</Tabs>

***

## Tool Vendor

Tool Vendorのツールは、インテグレーション（Slack、GitHub、Notion、Gmailなど100以上）ごとに専用のMCPツールを用意することなく、エージェントがそれらを発見・実行できるようにします。

**推奨ワークフロー：** `emma_search_tools` → `emma_get_tool_schema`（必要な場合） → `emma_execute_tool`

### emma\_search\_tools

キーワードでインテグレーションツールを検索します。名前、サービス、説明を含む一致するツールを返します。

<ParamField path="query" type="string" required>
  検索キーワード（自然言語またはキーワード）。

  **例：** `"post slack message"`、`"create github issue"`
</ParamField>

<ParamField path="service" type="string">
  オプションのサービスフィルタ。例：`"slack"`、`"github"`、`"notion"`、`"gmail"`
</ParamField>

<ParamField path="limit" type="integer" default="20">
  最大結果数（上限100）。
</ParamField>

<Tabs>
  <Tab title="リクエスト例">
    ```json theme={null}
    {
      "query": "post slack message",
      "service": "slack",
      "limit": 5
    }
    ```
  </Tab>

  <Tab title="レスポンス例">
    ```
    Found 1 tool(s) for "post slack message" (service: slack):

    - **slack_post_message** (slack)
      Post a message to a Slack channel or user.

    **Next steps:**
    1. Use `emma_get_tool_schema` to see the input schema for a tool
    2. Use `emma_execute_tool` to execute the tool with arguments
    ```
  </Tab>
</Tabs>

***

### emma\_get\_tool\_schema

特定のインテグレーションツールの入力引数のJSON Schemaを取得します。

<ParamField path="tool_name" type="string" required>
  正確なツール名（例：`"slack_post_message"`、`"github_create_issue"`）。`emma_search_tools`から取得します。
</ParamField>

<Tabs>
  <Tab title="リクエスト例">
    ```json theme={null}
    {
      "tool_name": "slack_post_message"
    }
    ```
  </Tab>

  <Tab title="レスポンス例">
    ````
    **slack_post_message**

    Post a message to a Slack channel or user.

    **Input Schema:**
    ```json
    {
      "type": "object",
      "properties": {
        "channel": { "type": "string", "description": "Channel name or ID, e.g. #general" },
        "text": { "type": "string", "description": "Message text to post" }
      },
      "required": ["channel", "text"]
    }
    ````

    **Required arguments:** channel, text

    **Next step:** Use `emma_execute_tool` with tool\_name="slack\_post\_message" and the required arguments.

    ````
    </Tab>
    </Tabs>

    ---

    ### emma_execute_tool

    特定のインテグレーションツールを引数付きで実行します。OAuthはemmaが処理します — ツールに未設定の認証が必要な場合、エラーの代わりに接続リンクが返されます。

    <ParamField path="tool_name" type="string" required>
    実行する正確なツール名（例：`"slack_post_message"`）。`emma_search_tools`から取得します。
    </ParamField>

    <ParamField path="arguments" type="string" required>
    ツールの引数を**JSON文字列**として指定（JSONオブジェクトではありません）。例：`'{"channel": "#general", "text": "Hello!"}'`。引数がないツールには`'{}'`を渡します。
    </ParamField>

    <ParamField path="session_id" type="string">
    ステートフル・マルチステップ実行用のオプションのセッションID。省略するとステートレス呼び出しとなり、新しいセッションIDが生成されて返されます。
    </ParamField>

    <Tabs>
    <Tab title="リクエスト例">
    ```json
    {
      "tool_name": "slack_post_message",
      "arguments": "{\"channel\": \"#general\", \"text\": \"Hello from Cursor!\"}"
    }
    ````
  </Tab>

  <Tab title="レスポンス例（成功時）">
    ```
    Tool: slack_post_message
    Duration: 412ms
    Session: tool_a1b2c3d4e5f6

    Result:
    {
      "ok": true,
      "message_ts": "1735282800.000100"
    }
    ```
  </Tab>

  <Tab title="レスポンス例（認証が必要な場合）">
    ```
    Authentication Required

    Tool: slack_post_message
    Service: slack
    Reason: auth_required
    Auth Type: oauth2

    Slack への接続が必要です。

    Connect Link: https://app.emma.ai/connect/slack?request=req_abc123

    Please ask the user to visit the connect link to authenticate, then retry the request.
    ```
  </Tab>
</Tabs>

<Note>
  `reason`が`auth_required`または`auth_expired`の場合は、`Connect Link`をユーザーに提示してください。ユーザーが認証を完了したら、同じ`emma_execute_tool`呼び出しを再試行します。
</Note>

***

## Skill Vendor

**Skill**とは、タスクの実行方法を記述した名前付きの再利用可能なプロンプトです — 実質的にはAgent Skill（`name` + `summary`/description + `instructions`/body）です。Skillはemmaのクラウドに保存されるため、マシン・IDE・エージェントを問わず再現可能で、emmaのWeb UIの**Skills**タブにも表示されます。

**推奨ワークフロー：** タスクを始める前に`emma_list_skills`で関連するSkillが既に存在するか確認し、`emma_get_skill`で内容を取得して自分で手順に従います。

### emma\_list\_skills

保存済みのSkillを新しい順に一覧表示します。デフォルトでは**全件**を返します（ページネーション対応）。`query`はオプションの絞り込みフィルタであり、必須のキーワード検索ではありません。

<ParamField path="query" type="string">
  Skillのname/summaryに対するオプションの絞り込みフィルタ。空欄で全件返します。
</ParamField>

<ParamField path="limit" type="integer" default="20">
  1ページあたりの最大件数（上限100）。
</ParamField>

<ParamField path="offset" type="integer" default="0">
  ページネーション用に読み飛ばす件数。
</ParamField>

<Tabs>
  <Tab title="リクエスト例">
    ```json theme={null}
    {
      "query": "",
      "limit": 20,
      "offset": 0
    }
    ```
  </Tab>

  <Tab title="レスポンス例">
    ```
    Showing 2 of 2 skill(s) (offset=0):

    - **Weekly Status Report** (skill_id: 3f1a9e2b-1234-4c56-9abc-1234567890ab)
      Gathers last week's closed issues and posts a summary to Slack #team.
    - **Daily Standup Reminder** (skill_id: 7c2b5f8d-5678-4d9e-bcde-234567890abc)
      Posts a standup reminder to Slack #general every weekday morning.

    **Next step:** Use `emma_get_skill` with a skill_id to read the full instructions, then follow them.
    ```
  </Tab>
</Tabs>

***

### emma\_get\_skill

Skillの完全な手順（本文）を取得します。返される内容はプロンプト/ワークフローであり、読んだ後はエージェント自身がその手順に従います。インテグレーションアクションが必要な場合は`emma_search_tools` / `emma_get_tool_schema` / `emma_execute_tool`を使用します。

<ParamField path="skill_id" type="string" required>
  正確なSkill ID。`emma_list_skills`から取得します。
</ParamField>

<Tabs>
  <Tab title="リクエスト例">
    ```json theme={null}
    {
      "skill_id": "3f1a9e2b-1234-4c56-9abc-1234567890ab"
    }
    ```
  </Tab>

  <Tab title="レスポンス例">
    ```
    **Weekly Status Report**

    Gathers last week's closed issues and posts a summary to Slack #team.

    **Instructions:**
    1. Use emma_execute_tool with github_list_issues to fetch issues closed in the last 7 days.
    2. Summarize them into 3-5 bullet points.
    3. Use emma_execute_tool with slack_post_message to post the summary to #team.

    **Next step:** Follow these instructions. Use `emma_execute_tool` for any integration actions required.
    ```
  </Tab>
</Tabs>

***

### emma\_create\_skill

再利用可能なワークフローを新しいSkillとして保存します。他のマシン・IDE・エージェントから再利用する価値のあるタスクを完了した後に使用します。3つの引数すべてが必須です。

<ParamField path="name" type="string" required>
  短く分かりやすいSkill名。
</ParamField>

<ParamField path="description" type="string" required>
  Skillが何を行い、いつ使うべきかの説明（`emma_list_skills`での発見に使用）。
</ParamField>

<ParamField path="body" type="string" required>
  従うべき手順・ワークフロー。関連するemmaツールを参照してください。
</ParamField>

<Tabs>
  <Tab title="リクエスト例">
    ```json theme={null}
    {
      "name": "Weekly Status Report",
      "description": "Gathers last week's closed issues and posts a summary to Slack #team.",
      "body": "1. Use emma_execute_tool with github_list_issues to fetch issues closed in the last 7 days.\n2. Summarize them into 3-5 bullet points.\n3. Use emma_execute_tool with slack_post_message to post the summary to #team."
    }
    ```
  </Tab>

  <Tab title="レスポンス例">
    ```
    Skill created.
    skill_id: 3f1a9e2b-1234-4c56-9abc-1234567890ab
    name: Weekly Status Report

    Retrieve it later with `emma_get_skill` or find it with `emma_list_skills`.
    ```
  </Tab>
</Tabs>

***

### emma\_update\_skill

既存のSkillを更新します。空でないフィールドのみが変更されます。

<ParamField path="skill_id" type="string" required>
  正確なSkill ID。`emma_list_skills`から取得します。
</ParamField>

<ParamField path="name" type="string">
  新しい名前（空欄で現在の値を維持）。
</ParamField>

<ParamField path="summary" type="string">
  新しい説明（空欄で現在の値を維持）。
</ParamField>

<ParamField path="instructions" type="string">
  新しい本文（空欄で現在の値を維持）。
</ParamField>

<Tabs>
  <Tab title="リクエスト例">
    ```json theme={null}
    {
      "skill_id": "3f1a9e2b-1234-4c56-9abc-1234567890ab",
      "instructions": "1. Use emma_execute_tool with github_list_issues (last 7 days).\n2. Summarize into bullet points.\n3. Post to Slack #team AND #eng-leads."
    }
    ```
  </Tab>

  <Tab title="レスポンス例">
    ```
    Skill updated.
    skill_id: 3f1a9e2b-1234-4c56-9abc-1234567890ab
    name: Weekly Status Report
    version: 2
    ```
  </Tab>
</Tabs>

***

### emma\_delete\_skill

Skillを削除します。

<ParamField path="skill_id" type="string" required>
  正確なSkill ID。`emma_list_skills`から取得します。
</ParamField>

<Warning>
  Skillの削除は永続的で、元に戻すことはできません。
</Warning>

<Tabs>
  <Tab title="リクエスト例">
    ```json theme={null}
    {
      "skill_id": "3f1a9e2b-1234-4c56-9abc-1234567890ab"
    }
    ```
  </Tab>

  <Tab title="レスポンス例">
    ```
    Skill deleted: 3f1a9e2b-1234-4c56-9abc-1234567890ab
    ```
  </Tab>
</Tabs>

***

## エラーレスポンス

| 状況                                                         | レスポンス                                                         |
| ---------------------------------------------------------- | ------------------------------------------------------------- |
| `emma_execute_tool` / `emma_get_tool_schema`に不明なツール名を渡した場合 | `Tool not found: <tool_name>`（`emma_search_tools`の利用を促すヒント付き） |
| Skill Vendorのいずれかのツールに不明な`skill_id`を渡した場合                  | `Skill not found: <skill_id>`（`emma_list_skills`の利用を促すヒント付き）  |
| `emma_execute_tool`の`arguments`に不正なJSONを渡した場合              | `Invalid JSON in arguments: ...`（期待される形式付き）                   |
| インテグレーションにOAuthが必要で未接続の場合                                  | `reason: "auth_required"`（または`"auth_expired"`）と`connect_link` |
| HTTPレベルの認証失敗（APIキーが不正/未指定）                                 | `401`と`error: "api_key_required"`または`"invalid_api_key"`       |
| リクエスト過多                                                    | `429`と`error: "rate_limit_exceeded"`、`Retry-After`ヘッダー        |