# API設計書

## 概要

本ドキュメントは、Nushellプロジェクトにおける通信プロトコルおよびインターフェースの設計を記述する。Nushellは従来のWebAPIアプリケーションではなく、シェル（コマンドラインインタプリタ）であるため、REST APIエンドポイントは存在しない。代わりに、以下の3つの主要なプロトコルインターフェースを提供する:

1. **Plugin Protocol** - Nushellエンジンとプラグイン間のJSON-RPCベース通信プロトコル
2. **Language Server Protocol (LSP)** - エディタとNushell言語サーバー間の通信
3. **Model Context Protocol (MCP)** - AIモデルとNushellサーバー間の通信

## 共通仕様

### 通信方式

| プロトコル | トランスポート | データフォーマット |
| --- | --- | --- |
| Plugin Protocol | stdin/stdout または Local Socket | JSON (MessagePack対応) |
| LSP | stdin/stdout | JSON-RPC 2.0 |
| MCP | stdin/stdout または HTTP (SSE) | JSON-RPC 2.0 |

### 共通エラーレスポンス

全プロトコルにおいて、エラーは `ShellError` 型として定義され、以下の形式で返される:

```json
{
  "error": "エラータイプ",
  "msg": "エラーメッセージ",
  "span": { "start": 0, "end": 10 },
  "help": "ヘルプメッセージ（オプション）"
}
```

---

## API一覧

### Plugin Protocol

| カテゴリ | メッセージタイプ | 方向 | 説明 |
| --- | --- | --- | --- |
| 初期化 | Hello | 双方向 | プロトコル情報の交換 |
| 呼び出し | Call (Metadata) | Engine -> Plugin | プラグインメタデータ取得 |
| 呼び出し | Call (Signature) | Engine -> Plugin | コマンドシグネチャ取得 |
| 呼び出し | Call (Run) | Engine -> Plugin | コマンド実行 |
| 呼び出し | Call (GetCompletion) | Engine -> Plugin | 補完候補取得 |
| 呼び出し | Call (CustomValueOp) | Engine -> Plugin | カスタム値操作 |
| 応答 | CallResponse | Plugin -> Engine | 呼び出しへの応答 |
| エンジン呼び出し | EngineCall | Plugin -> Engine | プラグインからエンジンへの呼び出し |
| ストリーム | Data/End/Drop/Ack | 双方向 | ストリームデータ制御 |
| 制御 | Goodbye | Engine -> Plugin | 終了通知 |
| 制御 | Signal | Engine -> Plugin | シグナル伝達 |

### LSP (Language Server Protocol)

| カテゴリ | メソッド | 説明 |
| --- | --- | --- |
| 初期化 | initialize | サーバー初期化 |
| テキスト同期 | textDocument/didOpen | ドキュメント開封通知 |
| テキスト同期 | textDocument/didChange | ドキュメント変更通知 |
| 補完 | textDocument/completion | コード補完 |
| ホバー | textDocument/hover | ホバー情報取得 |
| 定義 | textDocument/definition | 定義へ移動 |
| 参照 | textDocument/references | 参照検索 |
| リネーム | textDocument/rename | リネーム |
| シンボル | textDocument/documentSymbol | ドキュメントシンボル |
| シンボル | workspace/symbol | ワークスペースシンボル |
| ハイライト | textDocument/documentHighlight | ドキュメントハイライト |
| ヒント | textDocument/inlayHint | インレイヒント |
| セマンティック | textDocument/semanticTokens/full | セマンティックトークン |
| シグネチャ | textDocument/signatureHelp | シグネチャヘルプ |

### MCP (Model Context Protocol)

| カテゴリ | ツール名 | 説明 |
| --- | --- | --- |
| コマンド一覧 | list_commands | Nushellコマンド一覧取得 |
| ヘルプ | command_help | コマンドヘルプ取得 |
| 実行 | evaluate | Nushellコード実行 |

---

## 各APIエンドポイント定義

### Plugin Protocol

#### 1. Hello (プロトコル初期化)

プラグインとエンジン間で最初に交換されるメッセージ。プロトコルバージョンと対応機能を通知する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| メッセージタイプ | `Hello` |
| 方向 | 双方向（初回必須） |

**リクエスト/レスポンス形式**

```json
{
  "Hello": {
    "protocol": "nu-plugin",
    "version": "0.111.1",
    "features": ["LocalSocket"]
  }
}
```

| フィールド名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| protocol | string | O | プロトコル名（"nu-plugin"固定） |
| version | string | O | セマンティックバージョン |
| features | string[] | O | サポートする機能リスト |

**サポートされる機能（Features）**

| 機能名 | 説明 |
| --- | --- |
| LocalSocket | ローカルソケット通信対応 |

---

#### 2. Call - Metadata

プラグインのメタデータを取得する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| メッセージタイプ | `Call` |
| 呼び出しタイプ | `Metadata` |
| 方向 | Engine -> Plugin |

**リクエスト形式**

```json
{
  "Call": [1, "Metadata"]
}
```

**レスポンス形式**

```json
{
  "CallResponse": [1, {
    "Metadata": {
      "name": "plugin_name",
      "version": "1.0.0"
    }
  }]
}
```

---

#### 3. Call - Signature

プラグインが提供するコマンドのシグネチャを取得する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| メッセージタイプ | `Call` |
| 呼び出しタイプ | `Signature` |
| 方向 | Engine -> Plugin |

**リクエスト形式**

```json
{
  "Call": [1, "Signature"]
}
```

**レスポンス形式**

```json
{
  "CallResponse": [1, {
    "Signature": [
      {
        "name": "command_name",
        "description": "コマンドの説明",
        "input_type": "Any",
        "output_type": "Any",
        "required_positional": [],
        "optional_positional": [],
        "named": []
      }
    ]
  }]
}
```

---

#### 4. Call - Run

プラグインコマンドを実行する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| メッセージタイプ | `Call` |
| 呼び出しタイプ | `Run` |
| 方向 | Engine -> Plugin |

**リクエスト形式**

```json
{
  "Call": [1, {
    "Run": {
      "name": "command_name",
      "call": {
        "head": { "start": 0, "end": 10 },
        "positional": [],
        "named": {}
      },
      "input": "Empty"
    }
  }]
}
```

| フィールド名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| name | string | O | コマンド名 |
| call | EvaluatedCall | O | 呼び出し情報 |
| input | PipelineDataHeader | O | パイプライン入力データ |

**パイプラインデータヘッダー (PipelineDataHeader)**

| タイプ | 説明 |
| --- | --- |
| Empty | 入力なし |
| Value | 単一値 |
| ListStream | リストストリーム |
| ByteStream | バイトストリーム |

**レスポンス形式（成功時）**

```json
{
  "CallResponse": [1, {
    "PipelineData": {
      "Value": [
        { "int": 42 },
        null
      ]
    }
  }]
}
```

**レスポンス形式（エラー時）**

```json
{
  "CallResponse": [1, {
    "Error": {
      "error": "GenericError",
      "msg": "エラーメッセージ"
    }
  }]
}
```

---

#### 5. Call - GetCompletion

コマンド引数の補完候補を取得する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| メッセージタイプ | `Call` |
| 呼び出しタイプ | `GetCompletion` |
| 方向 | Engine -> Plugin |

**リクエスト形式**

```json
{
  "Call": [1, {
    "GetCompletion": {
      "name": "command_name",
      "arg_type": { "Positional": 0 },
      "call": {
        "call": { ... },
        "strip": false,
        "pos": 10
      }
    }
  }]
}
```

**レスポンス形式**

```json
{
  "CallResponse": [1, {
    "CompletionItems": [
      { "value": "option1", "description": "説明1" },
      { "value": "option2", "description": "説明2" }
    ]
  }]
}
```

---

#### 6. Call - CustomValueOp

カスタム値に対する操作を実行する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| メッセージタイプ | `Call` |
| 呼び出しタイプ | `CustomValueOp` |
| 方向 | Engine -> Plugin |

**サポートされる操作**

| 操作名 | 説明 |
| --- | --- |
| ToBaseValue | 基本値への変換 |
| FollowPathInt | 整数インデックスによるパス追跡 |
| FollowPathString | 文字列キーによるパス追跡 |
| PartialCmp | 部分比較 |
| Operation | 演算子操作 |
| Save | ファイル保存 |
| Dropped | ドロップ通知 |

---

#### 7. EngineCall (プラグインからエンジンへの呼び出し)

プラグインがエンジンの機能を呼び出す。

**サポートされるエンジン呼び出し**

| 呼び出し名 | 説明 |
| --- | --- |
| GetConfig | エンジン設定取得 |
| GetPluginConfig | プラグイン固有設定取得 |
| GetEnvVar | 環境変数取得 |
| GetEnvVars | 全環境変数取得 |
| GetCurrentDir | カレントディレクトリ取得 |
| AddEnvVar | 環境変数設定 |
| GetHelp | ヘルプ取得 |
| EnterForeground | フォアグラウンド移行 |
| LeaveForeground | フォアグラウンド離脱 |
| GetSpanContents | Span内容取得 |
| EvalClosure | クロージャ評価 |
| FindDecl | 宣言検索 |
| GetBlockIR | ブロックIR取得 |
| CallDecl | 宣言呼び出し |

---

#### 8. StreamMessage (ストリーム制御)

ストリームデータの送受信を制御する。

**メッセージタイプ**

| タイプ | 説明 |
| --- | --- |
| Data | ストリームデータ送信 |
| End | ストリーム終了 |
| Drop | ストリーム破棄（コンシューマ側） |
| Ack | データ受信確認（フロー制御） |

---

### Language Server Protocol (LSP)

#### 1. textDocument/completion

コード補完候補を取得する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| メソッド | `textDocument/completion` |
| 方向 | Client -> Server |

**リクエストパラメータ**

```json
{
  "textDocument": {
    "uri": "file:///path/to/file.nu"
  },
  "position": {
    "line": 10,
    "character": 5
  }
}
```

**レスポンス**

```json
{
  "isIncomplete": false,
  "items": [
    {
      "label": "ls",
      "kind": 3,
      "detail": "List the files in a directory"
    }
  ]
}
```

---

#### 2. textDocument/hover

カーソル位置の要素に関する情報を取得する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| メソッド | `textDocument/hover` |
| 方向 | Client -> Server |

**リクエストパラメータ**

```json
{
  "textDocument": {
    "uri": "file:///path/to/file.nu"
  },
  "position": {
    "line": 10,
    "character": 5
  }
}
```

**レスポンス**

```json
{
  "contents": {
    "kind": "markdown",
    "value": "## ls\n\nList the files in a directory..."
  },
  "range": {
    "start": { "line": 10, "character": 0 },
    "end": { "line": 10, "character": 2 }
  }
}
```

---

#### 3. textDocument/definition

シンボルの定義位置へ移動する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| メソッド | `textDocument/definition` |
| 方向 | Client -> Server |

**リクエストパラメータ**

```json
{
  "textDocument": {
    "uri": "file:///path/to/file.nu"
  },
  "position": {
    "line": 10,
    "character": 5
  }
}
```

**レスポンス**

```json
{
  "uri": "file:///path/to/definition.nu",
  "range": {
    "start": { "line": 5, "character": 0 },
    "end": { "line": 5, "character": 20 }
  }
}
```

---

#### 4. textDocument/references

シンボルの参照箇所を検索する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| メソッド | `textDocument/references` |
| 方向 | Client -> Server |

**リクエストパラメータ**

```json
{
  "textDocument": {
    "uri": "file:///path/to/file.nu"
  },
  "position": {
    "line": 10,
    "character": 5
  },
  "context": {
    "includeDeclaration": true
  }
}
```

**レスポンス**

```json
[
  {
    "uri": "file:///path/to/file1.nu",
    "range": { "start": { "line": 10, "character": 0 }, "end": { "line": 10, "character": 10 } }
  },
  {
    "uri": "file:///path/to/file2.nu",
    "range": { "start": { "line": 20, "character": 5 }, "end": { "line": 20, "character": 15 } }
  }
]
```

---

### MCP (Model Context Protocol)

#### 1. list_commands

利用可能なNushellコマンド一覧を取得する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| ツール名 | `list_commands` |
| トランスポート | stdio / HTTP |

**リクエストパラメータ**

```json
{
  "find": "file"
}
```

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| find | string | - | コマンド名、説明、検索語での絞り込み |

**レスポンス**

コマンド一覧が文字列として返される（`help commands` の出力形式）。

---

#### 2. command_help

特定のNushellコマンドのヘルプを取得する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| ツール名 | `command_help` |
| トランスポート | stdio / HTTP |

**リクエストパラメータ**

```json
{
  "name": "ls"
}
```

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| name | string | O | コマンド名 |

**レスポンス**

コマンドのヘルプ情報が文字列として返される（`help <command>` の出力形式）。

---

#### 3. evaluate

Nushellコードを実行する。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| ツール名 | `evaluate` |
| トランスポート | stdio / HTTP |

**リクエストパラメータ**

```json
{
  "input": "ls | where type == dir"
}
```

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| input | string | O | 実行するNushellソースコード |

**レスポンスフォーマット**

```json
{
  "cwd": "/path/to/current/dir",
  "history_index": 0,
  "timestamp": "2025-01-01T12:00:00",
  "output": "実行結果"
}
```

| フィールド名 | 型 | 説明 |
| --- | --- | --- |
| cwd | string | コマンド実行後のカレントディレクトリ |
| history_index | number | 履歴内の0ベースインデックス |
| timestamp | datetime | コマンド実行時刻 |
| output | string | コマンド出力（truncateされていない場合） |
| note | string | 出力がtruncateされた場合の通知 |

---

## MCP HTTP トランスポート仕様

MCPはHTTPトランスポートもサポートする。

### 接続情報

| 項目 | 内容 |
| --- | --- |
| プロトコル | HTTP/1.1 |
| エンドポイント | `http://0.0.0.0:{port}` |
| ストリーミング | Server-Sent Events (SSE) |

### 設定パラメータ

| パラメータ | デフォルト値 | 説明 |
| --- | --- | --- |
| SESSION_KEEP_ALIVE | 30分 | セッションアイドルタイムアウト |
| SESSION_CHANNEL_CAPACITY | 16 | セッションメッセージバッファ容量 |
| SSE_KEEP_ALIVE | 15秒 | SSEキープアライブping間隔 |
| SSE_RETRY | 3秒 | クライアント再接続リトライ間隔 |

---

## 備考

### Plugin Protocol バージョニング

- プロトコルバージョンはセマンティックバージョニングに従う
- 下位バージョンが上位バージョンとセマンティックに互換である場合、互換性ありと判定
- プレリリースバージョン（例: 1.2.3-nightly.1）は互換性チェック時に無視される

### LSP サポート機能

Nushell LSPは以下のサーバー機能をサポート:
- テキストドキュメント同期（増分更新）
- コード補完
- 定義へ移動
- 参照検索
- ドキュメントハイライト
- ドキュメントシンボル/ワークスペースシンボル
- ホバー情報
- インレイヒント
- リネーム（準備フェーズ含む）
- セマンティックトークン
- シグネチャヘルプ

### MCP 環境変数

| 変数名 | 説明 |
| --- | --- |
| NU_MCP_HISTORY_LIMIT | 履歴エントリ数上限（デフォルト: 100） |
| NU_MCP_OUTPUT_LIMIT | 出力サイズ上限（例: "10kb"） |
