otama

MCP サーバーで、Cursor、Claude Desktop、または独自のボイスエージェントなどの AI アシスタントに、ローカル git リポジトリへのアクセスを提供します。

読み取り操作は自由に実行されます。書き込みを行うツールは、最初に確認トークンと分かりやすい英語の要約を返し、そのトークンを使って2回目に呼び出されたときだけ動作します。アシスタントはコミットする前に確認を求めます。

You:  commit my changes in api-service with message "fix auth timeout"
LLM:  Commit 3 changed files in api-service with message 'fix auth timeout'. Confirm?
You:  yes
LLM:  Committed — a4f21c9 fix auth timeout

なぜ

多くのファイルシステム MCP サーバーは、モデルにディレクトリツリーへの無制限の読み書きアクセスを与えています。すべてのツール呼び出しを監視しているならそれで問題ありません。しかし、モデルがボイスアシスタントを操作している場合、無監視で実行されている場合、あるいはあなたの言葉を聞き間違えたばかりの場合には、それでは困ります。

otama はモデルが時々間違えることを前提にし、その影響を小さくします:

• パスサンドボックス。 すべてのパスは、設定したルートと照合される前に解決されます。..、シンボリックリンク、絶対パスによる逃げ道はありません。

• 2段階の確認。 トークンなしで呼び出された書き込みツールや実行ツールは、何も実行せず、何を行おうとしているかを説明するだけです。トークンは使い切りで、2分間で失効し、発行したツールに紐付けられます。

• コマンドの許可画面。 run_command は、許可外のものを確認の対象にしてそちらに判断を求めるのではなく、無条件で拒否します。聞き間違いが、rm -rf に対して「yes」を一度押すだけ、という距離にならないようにです。

Related MCP server: Git MCP Server

インストール

Python 3.11 以上と PATH に git が必要です。

git clone https://github.com/Ronith2906/otama.git
cd otama
python -m venv .venv
.venv/bin/pip install -r requirements.txt          # Windows: .venv\Scripts\pip.exe
cp otama.example.toml otama.toml

otama.toml を編集し、リポジトリを含むフォルダ（または複数のフォルダ）を project_roots に設定します。Windows ではスラッシュ（/）を使います。

[projects]
project_roots = ["C:/Users/you/code"]

確認:

.venv/bin/python -c "import asyncio; from projects_server import otama; print([t.name for t in asyncio.run(otama.list_tools())])"

ツール名が10個表示されたら、正常に動作しています。

接続する

Cursor の場合 — ~/.cursor/mcp.json。Claude Desktop の場合 — claude_desktop_config.json（設定 → 開発者 → 設定を編集）。どちらも同じ形です:

{
  "mcpServers": {
    "otama-projects": {
      "command": "/absolute/path/to/otama/.venv/bin/python",
      "args": ["/absolute/path/to/otama/projects_server.py"]
    }
  }
}

Windows では JSON パスで \\ を使います — C:\\Users\\you\\otama\\.venv\\Scripts\\python.exe。

アプリを完全に再起動してください。再読込では不十分です。MCP サーバーは起動時に読み込まれます。

ツール

読み取り — 即時実行

書き込み・実行 — 確認が必要

設定

[projects]
project_roots            = ["C:/Users/you/code"]
max_file_bytes           = 200000   # refuse to read anything larger
command_timeout_seconds  = 120
confirmation_ttl_seconds = 120      # how long a token stays valid

# run_command refuses anything not on this list. This is not something a
# confirmation can override — add what you actually use.
allowed_commands = ["git","npm","npx","pnpm","yarn","node",
                    "python","py","pip","pytest","ruff","uv",
                    "dotnet","cargo","go"]

コントリビューターへのメモ

2段階のパターンは stage()、redeem()、_expire() に実装されています。副作用のあるツールを追加する場合も、これを使います。

維持しておきたい重要な点があります: redeem() は、ツールの種類が一致しない場合、トークンを消費しません。モデルが誤って「Wrong tool（不応したツール）」を呼び出しても、ユーザーの承認を消耗させて、操作をやり直させるべきではありません。これは実際にテストで見つかったバグです。

新たな機能サーバーも同じ形にします — 1ファイル、1ドメイン、読み取りツールは自由、書き込みツールは制限付き、バック外の行為は確認の対象ではなく拒否の対象に。

ステータス

初期段階です。 projects サーバーはテスト済みで日々日常的に使用されています。より大きなボイスアシスタントプロジェクトの一部として、さらに機能サーバー（メディア、メール、ブラウザ）を計画中です。Issue・PR も歓迎します。

ライセンス

MIT