本仕様書は、コーディングエージェントにおいてテキストファイルの生成・編集をbhouston/mcp-server-text-editorを使用して行うための詳細設計を定義します。このMCPサーバーはClaude APIのテキストエディタツールと同一のAPIを提供し、コマンド実行Docker環境内でファイル操作を統一的に行うことを可能にします。
現行のコーディングエージェントでは、ファイル操作を以下の方法で行っています:
- GitHub MCP Server:
github_create_or_update_fileなどのAPIでファイルを直接リポジトリに反映 - GitLab MCP Server: 同様のAPIでMerge Requestにファイルを反映
この方式には以下の課題があります:
- ファイル編集がリポジトリAPIに依存し、ローカルファイルの柔軟な編集が困難
- 編集の単位がファイル全体となり、部分的な置換が非効率
- gitコマンドによる履歴管理やブランチ操作ができない
- Command Executor環境とGitHub/GitLab MCPの間でファイル状態の不整合が発生しうる
bhouston/mcp-server-text-editorをコマンド実行Docker環境内で動作させる- テキスト編集MCP有効時は、GitHub/GitLab MCPをLLMに提供しない
- ファイル生成・編集はtext-editor MCPで行い、gitコマンドでcommit/pushする
- 既存のCommand Executor環境と統合して動作する
- デフォルトで有効化する
- Claudeのテキストエディタツールと同様のプロンプトを使用する
- bhouston/mcp-server-text-editor GitHub
- Claude テキストエディタツール
- Command Executor MCP Server連携仕様
- 複数言語対応実行環境仕様
flowchart TD
subgraph CodingAgent[コーディングエージェント]
TaskHandler[TaskHandler]
PlanningCoordinator[PlanningCoordinator]
MCPClient[MCPToolClient]
ExecutionManager[ExecutionEnvironmentManager]
end
subgraph DockerHost[Docker Host]
DockerAPI[Docker API]
subgraph ExecutionContainer[実行環境コンテナ]
TextEditorMCP[Text Editor MCP Server]
GitClient[gitコマンド]
ProjectFiles[プロジェクトファイル]
WorkDir[作業ディレクトリ]
end
end
subgraph GitPlatform[Git Platform]
GitHub[GitHub]
GitLab[GitLab]
end
TaskHandler --> PlanningCoordinator
PlanningCoordinator --> MCPClient
MCPClient --> TextEditorMCP
ExecutionManager --> DockerAPI
DockerAPI --> ExecutionContainer
TextEditorMCP --> ProjectFiles
GitClient --> |push| GitPlatform
テキスト編集MCP機能が有効な場合、以下のMCP構成となります:
| MCP Server | 提供元 | 提供先 | 状態 |
|---|---|---|---|
| text-editor | コマンド実行コンテナ内 | LLM | 有効(新規追加) |
| command-executor | ExecutionEnvironmentManager | LLM | 有効(既存) |
| github | 外部プロセス | LLM | 無効化 |
| gitlab | 外部プロセス | LLM | 無効化 |
bhouston/mcp-server-text-editorをコマンド実行コンテナ内で動作させます。
責務:
- ファイルの表示(view)
- ファイルの新規作成(create)
- 文字列置換による編集(str_replace)
- 行挿入(insert)
- 編集の取り消し(undo_edit)
既存のExecutionEnvironmentManagerを拡張し、text-editor MCPの管理機能を追加します。
追加責務:
- コンテナ起動時にtext-editor MCPサーバーを開始
- text-editor MCPへのツール呼び出し中継
- git操作の実行(commit, push)
bhouston/mcp-server-text-editorは以下のツールを提供します。ツール名はtext_editorです。
ファイルの内容またはディレクトリ構造を表示します。
パラメータ:
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
| command | string | Yes | "view" |
| path | string | Yes | 表示対象のファイルまたはディレクトリパス |
| view_range | [number, number] | No | 表示する行範囲 [開始行, 終了行]。ファイルの場合のみ有効 |
使用例:
{
"command": "view",
"path": "/workspace/project/src/main.py",
"view_range": [1, 50]
}新しいファイルを作成します。
パラメータ:
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
| command | string | Yes | "create" |
| path | string | Yes | 作成するファイルのパス |
| file_text | string | Yes | ファイルの内容 |
使用例:
{
"command": "create",
"path": "/workspace/project/src/utils.py",
"file_text": "def helper_function():\n pass\n"
}ファイル内の文字列を置換します。
パラメータ:
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
| command | string | Yes | "str_replace" |
| path | string | Yes | 編集対象のファイルパス |
| old_str | string | Yes | 置換対象の文字列(完全一致) |
| new_str | string | Yes | 置換後の文字列 |
使用例:
{
"command": "str_replace",
"path": "/workspace/project/src/main.py",
"old_str": "def old_function():\n pass",
"new_str": "def new_function():\n return True"
}指定した行に新しいテキストを挿入します。
パラメータ:
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
| command | string | Yes | "insert" |
| path | string | Yes | 編集対象のファイルパス |
| insert_line | number | Yes | 挿入位置の行番号 |
| new_str | string | Yes | 挿入するテキスト |
使用例:
{
"command": "insert",
"path": "/workspace/project/src/main.py",
"insert_line": 5,
"new_str": "# 新しいコメント\n"
}直前のファイル編集を取り消します。
パラメータ:
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
| command | string | Yes | "undo_edit" |
| path | string | Yes | 取り消し対象のファイルパス |
使用例:
{
"command": "undo_edit",
"path": "/workspace/project/src/main.py"
}MCPクライアントに登録されるツール名はtext_editorです。function callingでは以下の形式で呼び出します:
text_editor_<command>
例:text_editor_view, text_editor_str_replace
すべての言語別実行環境イメージにmcp-server-text-editorをプリインストールします。
各Dockerfileに以下を追加します:
- Node.js(text-editor MCPサーバー実行用)
mcp-server-text-editorパッケージ(バージョン固定)
# 既存のベース構成に追加
# Node.js インストール(text-editor MCP用)
# セキュリティ向上のため、GPG署名付きの公式リポジトリを使用
ENV NODE_MAJOR=20
RUN apt-get update && \
apt-get install -y ca-certificates curl gnupg && \
mkdir -p /etc/apt/keyrings && \
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | \
gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg && \
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | \
tee /etc/apt/sources.list.d/nodesource.list && \
apt-get update && \
apt-get install -y nodejs && \
rm -rf /var/lib/apt/lists/*
# mcp-server-text-editorのプリインストール(バージョン固定)
ARG TEXT_EDITOR_MCP_VERSION=1.0.0
RUN npm install -g mcp-server-text-editor@${TEXT_EDITOR_MCP_VERSION}text-editor MCPサーバーはコンテナ内で常駐プロセスとして起動します。
npx -y mcp-server-text-editorコンテナ起動後、プロジェクトクローン完了後に起動します。
- プロトコル: stdio(標準入出力)
- フォーマット: JSON-RPC 2.0(MCP標準)
sequenceDiagram
participant EM as ExecutionEnvironmentManager
participant Container as 実行コンテナ
participant TextEditor as Text Editor MCP
EM->>Container: コンテナ起動
Container-->>EM: 起動完了
EM->>Container: プロジェクトクローン
Container-->>EM: クローン完了
EM->>Container: text-editor MCP起動
Container->>TextEditor: npx mcp-server-text-editor
TextEditor-->>Container: 起動完了
Container-->>EM: MCP準備完了
テキスト編集MCP機能が有効な場合(デフォルト)、以下のMCPサーバーをLLMに提供しません:
githubMCPサーバーgitlabMCPサーバー
テキスト編集MCP機能が有効な場合、GitHub/GitLab MCPのツールはシステムプロンプトおよびLLMに提供するツール一覧から自動的に除外されます。
GitHub/GitLab MCPの主要機能は以下で代替します:
| GitHub/GitLab MCP機能 | 代替手段 |
|---|---|
| ファイル作成・更新 | text_editor(create, str_replace) |
| ファイル取得 | text_editor(view) |
| ブランチ操作 | gitコマンド(command-executor経由) |
| コミット | gitコマンド(command-executor経由) |
| プッシュ | gitコマンド(command-executor経由) |
| Issue/PR操作 | 引き続きMCP経由(別途対応) |
ファイル操作以外のGitHub/GitLab機能(Issue操作、PR/MRの作成・更新、ラベル操作等)は、コーディングエージェントのTaskHandler内部で直接API呼び出しにより行います。LLMからのツール呼び出しは不要です。
テキスト編集後のファイルは、gitコマンドを使用してバージョン管理・リモートリポジトリへの反映を行います。
flowchart TD
A[ファイル編集完了] --> B[git add]
B --> C[git commit]
C --> D[git push]
D --> E{pushエラー?}
E -->|No| F[完了]
E -->|Yes| G[git pull --rebase]
G --> H{コンフリクト?}
H -->|No| D
H -->|Yes| I[LLMにコンフリクト解決を依頼]
システムプロンプトでLLMに以下のgitコマンドの使用を推奨します:
git status
git diff
git diff --stagedgit add <file>
git add .git commit -m "コミットメッセージ"git push origin <branch>git pull --rebase origin <branch>
# コンフリクトがある場合はtext_editorで解決後
git add <resolved_files>
git rebase --continuegitコマンドでのpushに必要な認証情報は、コンテナ起動時に設定済みです(Command Executor MCP仕様参照)。
テキスト編集MCP機能が有効な場合、システムプロンプトに以下を追加します。
## Text Editor Tool
You have access to a text editor tool (`text_editor`) for viewing, creating, and editing files in the project workspace.
### Available Commands
#### 1. view - View file or directory contents
View the content of a file or list directory contents.
**Parameters:**
- `command`: "view" (required)
- `path`: File or directory path (required)
- `view_range`: [start_line, end_line] - Optional line range for files
**Example:**
```json
{"command": "view", "path": "/workspace/project/src/main.py", "view_range": [1, 50]}
Create a new file with specified content. The file must not already exist.
Parameters:
command: "create" (required)path: Path for the new file (required)file_text: Content for the new file (required)
Example:
{"command": "create", "path": "/workspace/project/src/utils.py", "file_text": "def helper():\n pass\n"}Replace a specific string in a file. The old_str must match exactly one location in the file.
Parameters:
command: "str_replace" (required)path: File path (required)old_str: Exact string to replace (required)new_str: Replacement string (required)
Important:
- The
old_strmust match EXACTLY one or more consecutive lines - Include enough context to make the match unique
- Preserve leading/trailing whitespace exactly
Example:
{"command": "str_replace", "path": "/workspace/project/src/main.py", "old_str": "def old():\n pass", "new_str": "def new():\n return True"}Insert new text at the specified line number.
Parameters:
command: "insert" (required)path: File path (required)insert_line: Line number to insert at (required)new_str: Text to insert (required)
Example:
{"command": "insert", "path": "/workspace/project/src/main.py", "insert_line": 5, "new_str": "# New comment\n"}Revert the most recent edit to a file.
Parameters:
command: "undo_edit" (required)path: File path (required)
Example:
{"command": "undo_edit", "path": "/workspace/project/src/main.py"}- Before editing: Always use
viewto understand the current file structure - Precise matching: For
str_replace, include enough surrounding context to ensure unique matching - Incremental edits: Make small, focused changes rather than replacing large blocks
- Verify changes: After editing, use
viewto confirm the changes were applied correctly
#### 7.1.2 gitワークフロー説明
After making file changes with the text editor, you must commit and push your changes using git commands.
-
Check status: Review what files have been modified
git status git diff
-
Stage changes: Add modified files to staging
git add <modified_files> # or for all changes git add .
-
Commit changes: Create a commit with a descriptive message
git commit -m "feat: description of changes" -
Push changes: Push to the remote branch
git push origin <branch_name>
If push fails due to remote changes:
-
Pull with rebase:
git pull --rebase origin <branch_name>
-
If conflicts occur, resolve them using the text editor, then:
git add <resolved_files> git rebase --continue
-
Push again:
git push origin <branch_name>
- Always commit and push your changes before completing the task
- Use meaningful commit messages that describe the changes
- If you encounter authentication errors, report them in your response
- The working directory is
/workspace/project/
### 7.2 プロンプトテンプレートファイル
新規ファイル`system_prompt_text_editor.txt`を作成し、上記内容を配置します。
### 7.3 プロンプト挿入位置
- Command Executor機能説明セクションの直後
- Behavior Rulesセクションの直前
---
## 8. 設定ファイル仕様
### 8.1 config.yamlへの追加設定
```yaml
# テキスト編集MCP Server連携設定
text_editor_mcp:
# 機能の有効/無効(デフォルト: true)
# 環境変数 TEXT_EDITOR_MCP_ENABLED で上書き可能
# 有効時はGitHub/GitLab MCPが自動的に無効化され、
# ファイル操作はtext_editorとgitコマンドで行う
enabled: true
# MCP Server設定
mcp_server:
# サーバー名
name: "text-editor"
# コマンド
command:
- "npx"
- "-y"
- "mcp-server-text-editor"
| 環境変数名 | 説明 | デフォルト値 |
|---|---|---|
| TEXT_EDITOR_MCP_ENABLED | テキスト編集MCP機能の有効/無効 | true |
classDiagram
class ExecutionEnvironmentManager {
-docker_client
-config
-active_containers: Dict
-text_editor_processes: Dict
+prepare(task, environment_name) ContainerInfo
+execute_command(command, working_directory) ExecutionResult
+call_text_editor_tool(tool_name, arguments) ToolResult
+cleanup(task_uuid)
-_start_text_editor_mcp(container_id)
-_stop_text_editor_mcp(container_id)
}
class TextEditorMCPClient {
-process: Process
-container_id: str
+start()
+stop()
+call_tool(command, arguments) ToolResult
-_send_request(request) Response
-_receive_response() Response
}
class MCPToolClient {
-mcp_clients: Dict
-text_editor_client: TextEditorMCPClient
-config: Config
+get_tools_for_llm() List~Tool~
+call_tool(tool_name, arguments) ToolResult
-_should_exclude_git_platform_tools() bool
}
class ToolResult {
+success: bool
+content: str
+error: str
}
ExecutionEnvironmentManager --> TextEditorMCPClient
MCPToolClient --> TextEditorMCPClient
TextEditorMCPClient --> ToolResult
追加メソッド:
_start_text_editor_mcp(container_id): コンテナ内でtext-editor MCPサーバーを起動_stop_text_editor_mcp(container_id): text-editor MCPサーバーを停止call_text_editor_tool(tool_name, arguments): text-editorツールを呼び出し
text-editor MCPサーバーとの通信を管理するクラスです。
メソッド:
start(): MCPサーバープロセスを起動stop(): MCPサーバープロセスを停止call_tool(command, arguments): ツールを呼び出し_send_request(request): JSON-RPCリクエストを送信_receive_response(): JSON-RPCレスポンスを受信
追加メソッド:
_should_exclude_git_platform_tools(): GitHub/GitLabツールを除外すべきか判定get_tools_for_llm(): 設定に応じてフィルタリングされたツール一覧を返す
sequenceDiagram
participant TG as TaskGetter
participant TH as TaskHandler
participant PC as PlanningCoordinator
participant EM as ExecutionEnvironmentManager
participant TE as TextEditorMCP
participant LLM as LLMClient
TG->>TH: タスク取得
TH->>PC: PlanningCoordinator作成
rect rgb(200, 220, 255)
Note over PC,LLM: 計画フェーズ
PC->>LLM: 計画作成依頼
LLM-->>PC: 計画(JSON)
end
rect rgb(255, 220, 200)
Note over PC,TE: 環境準備
PC->>EM: prepare(task, environment)
EM->>EM: コンテナ起動
EM->>EM: プロジェクトクローン
EM->>TE: text-editor MCP起動
TE-->>EM: 起動完了
EM-->>PC: ContainerInfo
end
rect rgb(220, 255, 200)
Note over PC,TE: 実行フェーズ
loop タスク処理ループ
PC->>LLM: メッセージ送信
LLM-->>PC: 応答(function calls)
alt text_editor呼び出し
PC->>TE: call_tool(command, args)
TE-->>PC: ToolResult
else command-executor呼び出し
PC->>EM: execute_command(command)
EM-->>PC: ExecutionResult
end
PC->>LLM: 結果送信
end
end
PC-->>TH: 成功
TH->>EM: cleanup(task_uuid)
EM->>TE: MCP停止
EM->>EM: コンテナ削除
sequenceDiagram
participant LLM as LLMClient
participant PC as PlanningCoordinator
participant TE as TextEditorMCP
participant CE as CommandExecutor
Note over LLM,CE: ファイル編集シナリオ
LLM->>PC: text_editor_view呼び出し
PC->>TE: view(path)
TE-->>PC: ファイル内容
PC->>LLM: 結果送信
LLM->>PC: text_editor_str_replace呼び出し
PC->>TE: str_replace(path, old, new)
TE-->>PC: 編集結果
PC->>LLM: 結果送信
LLM->>PC: command-executor_execute_command呼び出し
PC->>CE: git status
CE-->>PC: 変更ファイル一覧
PC->>LLM: 結果送信
LLM->>PC: command-executor_execute_command呼び出し
PC->>CE: git add & commit & push
CE-->>PC: push結果
PC->>LLM: 結果送信
すべての言語別実行環境イメージに以下を追加します。
# Node.js インストール(text-editor MCP用)
# セキュリティ向上のため、GPG署名付きの公式リポジトリを使用
ENV NODE_MAJOR=20
RUN apt-get update && \
apt-get install -y ca-certificates curl gnupg && \
mkdir -p /etc/apt/keyrings && \
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | \
gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg && \
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | \
tee /etc/apt/sources.list.d/nodesource.list && \
apt-get update && \
apt-get install -y --no-install-recommends nodejs && \
rm -rf /var/lib/apt/lists/*
# mcp-server-text-editorのプリインストール(バージョン固定)
ARG TEXT_EDITOR_MCP_VERSION=1.0.0
RUN npm install -g mcp-server-text-editor@${TEXT_EDITOR_MCP_VERSION}Node.js環境イメージでは既にNode.jsがインストールされているため、mcp-server-text-editorのインストールのみ追加します。
# mcp-server-text-editorのプリインストール(バージョン固定)
ARG TEXT_EDITOR_MCP_VERSION=1.0.0
RUN npm install -g mcp-server-text-editor@${TEXT_EDITOR_MCP_VERSION}特別な変更は不要です。各言語別Dockerfileで直接docker buildを実行します。
原因:
- Node.jsが正しくインストールされていない
- mcp-server-text-editorパッケージが見つからない
対応:
- エラーログを記録
- text-editor機能なしで処理を継続(フォールバック)
- Issue/MRにエラーコメントを投稿
原因:
- ファイルが存在しない(view, str_replace)
- ファイルが既に存在する(create)
- 置換対象が見つからない/複数見つかる(str_replace)
対応:
- エラー内容をLLMに通知
- LLMが代替手段を検討
- 必要に応じてリフレクション実行
原因:
- トークンの期限切れ
- 権限不足
対応:
- エラー内容をLLMに通知
- タスクをエラー状態で終了
- Issue/MRにエラーコメントを投稿
原因:
- リモートブランチに他のコミットがある
対応:
- LLMにコンフリクト解決を依頼
- text_editorでコンフリクトマーカーを解決
- rebase継続またはmerge完了
text-editor MCPはコンテナ内で動作するため、コンテナ外のファイルにはアクセスできません。
制限範囲:
/workspace/project/配下のみアクセス可能- コンテナ外のファイルシステムは保護される
gitの認証情報はCommand Executor MCP仕様と同様に一時的に使用され、永続化されません。
文書バージョン: 1.0
最終更新日: 2024-11-30
ステータス: 設計中