local-code-agent

FastMCP ベースで開発されたローカル MCP サーバー：外部 AI（ChatGPT、Claude など）が HTTP 経由でローカルワークスペースをリモート操作できるようにします——ファイルの読み書き/編集、検索、シェルコマンド、Git 操作——さらにサンドボックス分離、機密ファイル保護、監査ログを提供します。

このプロジェクトには AI/LLM ロジックは含まれておらず、ツール層のサービスとセキュリティ制御のみが含まれています。

環境要件

• Python 3.10+（FastMCP の必須要件）

• pip install -r requirements.txt（fastmcp、pyyaml）

Related MCP server: OpenAI Secure MCP Tunnel

クイックスタート

方法1：GUI（推奨）

python start.py

コンソールウィンドウの操作手順：

1. ワークスペースフォルダ：「選択…」をクリックしてフォルダを指定します。AI のすべての操作はこのフォルダ内に制限され（サンドボックス）、フォルダを変更するとサンドボックスのルートが切り替わります。

2. 接続プロンプト：ウィンドウ中央に「接続プロンプト」カードがあり、中のテキストをコピーして Web 版 AI に送信すると、AI はその設定に従ってこの MCP サーバーにバインドされます（トークン不要）。

3. ポート：デフォルトは 8000。使用中の場合は変更できます。

4. 読み取り専用モード：チェックすると書き込み/編集/コマンド系ツールがすべて拒否され、実行中の切り替えも即座に有効になります。

5. 「サービス開始」をクリック → ステータスバーにバージョン、読み取り専用状態、ワークスペース、稼働時間が表示され、ログ領域にサービスログがリアルタイムで出力されます。

6. 停止：「サービス停止」をクリックするか、ウィンドウを直接閉じます（確認が表示されます）。

方法2：コマンドライン

# 1. 安装依赖
pip install -r requirements.txt

# 2. 启动服务（默认监听 127.0.0.1:8000，MCP 路径 /mcp，无需 Token）
python server.py

オプション引数：--workspace D:\projects\my-project（サンドボックスのルートディレクトリ）、--host 0.0.0.0（LAN アクセスを許可）、--port 9000。停止は Ctrl+C。

検証とヘルスチェック

サービス起動後、GET http://127.0.0.1:8000/health にアクセスします（認証不要）。戻り値：

{ "status": "ok", "service": "local-code-agent", "version": "0.1.0",
  "workspace": "D:\\projects\\my-project", "readonly": false,
  "uptime_seconds": 3 }

その他のエンドポイント（/mcp を含む）は認証なしで直接アクセスできます。

LAN アクセス

デフォルトでは 127.0.0.1 のみをリッスンし、このマシンからのみ接続可能です。同じ LAN 内の他のデバイスからアクセスする場合：

python server.py --host 0.0.0.0

クライアント接続アドレス：http://<本機のLAN IP>:8000/mcp（本機の IP は ipconfig で確認）。LAN に公開すると、同じネットワークセグメントのデバイスが認証なしでアクセスできるため、十分注意してください。

パブリックネットワークに直接公開することは推奨しません。パブリックアクセスが必要な場合は、リバースプロキシソリューション（Nginx + TLS、frp、その他のトンネルツール）を用意し、プロキシ層で HTTPS と認証を強制してください。

GUI（オプション）

コマンドラインを書かなくても使用できます。tkinter は Python 標準ライブラリのため、追加インストールは不要です。

python start.py

コンソール機能：

• ワークスペースフォルダ：「選択…」をクリックしてフォルダ選択ダイアログを開きます。一度に選択できるフォルダは 1 つだけで、AI のすべての操作はそのフォルダ（サンドボックス）内に制限され、フォルダを変更すると現在の選択が置き換えられます。

• 接続プロンプト：編集可能なプロンプトテキストが組み込まれており、「プロンプトをコピー」をクリックしてコピーし、Web 版 AI に送信すると MCP バインドが完了します。トークンは不要です。

• ポート / 読み取り専用モード：リッスンポートを設定。読み取り専用をチェックすると書き込み/編集/コマンドツールが無効になります。

• サービス開始 / 停止：GUI プロセス内で FastMCP を起動（バックグラウンドスレッド + uvicorn）、独立したログハンドラーを使用し、停止時はサービススレッドの完了を待ちます。

• 実行中の切り替え：ワークスペースの変更や読み取り専用のチェックは即座に有効になり、再起動は不要です。ポートの変更はサービスの再起動が必要です。

• ステータスバー：/health をポーリングし、バージョン、読み取り専用状態、現在のワークスペース、稼働時間を表示します。

• ログ領域：サービス出力をリアルタイム表示し、ANSI エスケープコードを自動クリーンアップ、右クリックでコピー可能、600 行を超えると自動で切り詰めます。

GUI とコマンドラインは同じサンドボックス、監査メカニズムを共有し、接続方法も同じです。

クライアント接続

ローカルクライアント：URL に http://127.0.0.1:8000/mcp を入力。LAN クライアントは http://<本機のLAN IP>:8000/mcp（サーバーは --host 0.0.0.0 で起動する必要があります）。認証は不要です。

Claude Desktop の claude_desktop_config.json：

{
  "mcpServers": {
    "local-code-agent": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

ツール一覧

セキュリティモデル

• サンドボックス：すべてのパスは realpath で解決され、ワークスペースのルートディレクトリ内にある必要があります（シンボリックリンクによるエスケープをブロック）。../ や絶対パスでは範囲外に出られません。

• 認証：トークン認証はありません。サービスはデフォルトで本機の 127.0.0.1 のみをリッスンします。外部公開が必要な場合は、リバースプロキシ層で認証を追加してください。

• 危険な操作の確認：Git コミットはリクエストヘッダー x-confirm: true がある場合のみ実行されます。

• 機密ファイル：.env、.env.*、*.pem、*.key、id_rsa、.ssh/、.aws/、credentials は任意のパス階層でブロックされます。統一された「access denied」を返し、ファイルの存在を公開しません。

• ダウンロード：任意の HTTP(S) ホストをサポート。リダイレクト禁止。50MB を超えると中止し、不完全なファイルを削除します。

• 監査ログ：JSON 行形式、10MB × 5 でローテーション。時間、ツール名、マスクされたパラメータ、結果、所要時間を記録します。

• 読み取り専用モード：python server.py --readonly または GUI でチェック。書き込み/コマンドツールは表示されたままですが、呼び出し時に read-only mode が返されます。実行中に切り替え可能です。

設定の優先順位

ワークスペース：--workspace > 環境変数 MCP_WORKSPACE > config.yaml（デフォルト .）。その他の設定はすべて config.yaml から取得されます（詳細はファイル内のデフォルト値を参照）。

プロジェクト構造

server.py                 # FastMCP 入口：配置、认证、/health
tool_registry.py          # 工具注册（与生命周期分离）
config.py / config.yaml   # 默认值 + YAML
sandbox.py                # 路径沙盒 + 敏感文件过滤
audit.py                  # 轮转 JSON 审计日志
tools/file_ops.py         # 读/写/编辑/列目录/搜索
tools/file_management.py  # 删/改名/复制/建目录/stat/tail/glob
tools/download.py         # HTTP(S) 下载（无域名白名单）
tools/command.py          # 同步 run_command（测试/非流式）
tools/git_ops.py          # status/diff/log/branch/commit
runtime.py                # 运行时只读标志
gui/                      # tkinter 控制台（进程内服务）
start.py                  # GUI 入口
tests/                    # test_core.py + test_extra.py

既知の制限

• Python 3.8 ではこのサービスを実行できません（fastmcp は 3.10+ が必要）。ロジックモジュールは 3.8 と互換性があり、python tests/test_core.py で自己チェックできます。

• run_command は SSE ストリーミング出力で、合計タイムアウト上限は 3600 秒です。

• 単一ワークスペースのみをサポート。複数ワークスペースの切り替えとセッションレベルのコンテキストは未実装です（YAGNI）。