local-code-agent

FastMCP ベースのローカル MCP サーバー：外部 AI（ChatGPT、Claude 等）が Cloudflare Tunnel による安全なトンネリングを介して、リモートからローカルワークスペースを操作できるようにします（ファイルの読み書き/編集、検索、シェルコマンド、Git 操作）。Bearer Token 認証、サンドボックス分離、監査ログを提供します。

本プロジェクトには AI/LLM のロジックは含まれず、ツールレイヤーのサービスとトンネル設定のみを提供します。

環境要件

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

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

クイックスタート

# 1. 安装依赖
pip install -r requirements.txt
set MCP_AUTH_TOKEN=your_long_random_token
set MCP_WORKSPACE=D:\projects\my-project

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

# 3. 公网穿透（临时域名）
cloudflared tunnel --url http://127.0.0.1:8000

# 固定域名（绑定自有域名）
cloudflared tunnel --url http://127.0.0.1:8000 --hostname mcp.yourdomain.com

ヘルスチェック：GET http://127.0.0.1:8000/health（デフォルトでは認証不要。その他のエンドポイントは Bearer Token が必要です）。

グラフィカルインターフェース（オプション）

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

python -m gui.app

コンソール機能：

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

• 認証 Token：起動時にランダムな Token が自動生成され、「再生成」をクリックして変更可能。この Token を AI クライアントの Authorization: Bearer ... に設定する必要があります。

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

• サービス開始 / 停止：server.py を子プロセスとして実行。停止するとプロセスが終了します。

• ステータスバー：/health をポーリングし、サービスのバージョン、現在のワークスペース、稼働時間を表示。cloudflared トンネルコマンドのワンクリックコピーもサポート。

• ログエリア：サーバーの子プロセス出力をリアルタイム表示。600 行を超えると自動的に切り詰められます。

GUI は server.py のランチャーであり、同一の認証、サンドボックス、監査セキュリティメカニズムを継承します。公開ネットワークへの接続方法はコマンドラインと同じです。

クライアント連携

ChatGPT Custom Connector：URL に https://<tunnel-host>/mcp を入力し、リクエストヘッダーに Authorization: Bearer your_long_random_token を追加します。

Claude Desktop の claude_desktop_config.json：

{
  "mcpServers": {
    "local-code-agent": {
      "url": "https://mcp.yourdomain.com/mcp",
      "headers": { "Authorization": "Bearer your_long_random_token" }
    }
  }
}

ツール一覧

セキュリティモデル

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

• 認証：FastMCP DebugTokenVerifier が Bearer Token を検証します。Token は MCP_AUTH_TOKEN からのみ読み取られます（開発時は --token を使用可能）。存在しない場合は起動が拒否されます。

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

• コマンドホワイトリスト：config.yaml 内の command_allow、command_deny、danger_commands（x-confirm: true が必要）。

• ダウンロード：download_allow_domains 内の http(s) ホストのみ許可。リダイレクト禁止。50MB を超えると中断し、不完全なファイルを削除します。

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

• 読み取り専用モード：python server.py --readonly で、読み取り/検索/Git 参照系ツールのみを登録します。

設定の優先順位

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

プロジェクト構造

server.py                 # FastMCP 入口：配置、认证、/health
tool_registry.py          # 工具注册（与生命周期分离）
config.py / config.yaml   # 默认值 + YAML
sandbox.py                # 路径沙盒 + 敏感文件过滤
command_whitelist.py      # 命令白名单校验
audit.py                  # 轮转 JSON 审计日志
tools/file_ops.py         # 读/写/编辑/列目录/搜索
tools/file_management.py  # 删/改名/复制/建目录/stat/tail/glob
tools/download.py         # 域名白名单下载
tools/command.py          # 同步 run_command（测试/非流式）
tools/git_ops.py          # status/diff/log/branch/commit
gui/                      # tkinter 启动器
start.py / start.spec     # GUI 入口 + PyInstaller onedir
tests/                    # test_core.py + test_extra.py

既知の制限

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

• Cloudflare Tunnel のデフォルトリクエストタイムアウトは約 100 秒です。run_command は SSE ストリーミング。合計タイムアウト上限は 3600 秒です。

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

• パッケージ化：pip install -r requirements-build.txt && pyinstaller start.spec、成果物は dist/start/start.exe。GUI では手動で「サービス開始」をクリックする必要があります。