otama

Сервер MCP, который даёт ИИ-ассистентам — Cursor, Claude Desktop или вашему собственному голосовому агенту — доступ к локальным git-репозиториям.

Операции чтения работают свободно. Всё, что пишет, сначала возвращает токен подтверждения и краткое описание простым языком, а действует только при повторном вызове с этим токеном. Ассистент спрашивает, прежде чем что-либо закоммитить.

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 исходит из того, что модель иногда ошибается, и сводит последствия к минимуму:

• Песочница для путей. Каждый путь преобразуется до того, как он проверяется по настроенным корням. .., симлинки и абсолютные пути не могут выбраться наружу.

• Двухфазное подтверждение. Инструменты записи и выполнения, вызванные без токена, ничего не делают, а лишь описывают, что они сделали бы. Токены одноразовые, истекают через две минуты и привязаны к инструменту, который их выдал.

• Список разрешённых команд. run_command категорически отвергает всё, что вне списка, а не предлагает подтверждение. Одна ошибка слуха не должна быть на расстоянии одного «да» от rm -rf.

Related MCP server: Git MCP Server

Установка

Требуется Python 3.11+ и git в PATH.

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())])"

Десять инструментов в списке — значит, вы работаете.

Подключение

Cursor — ~/.cursor/mcp.json
Claude Desktop — claude_desktop_config.json (Settings → Developer → Edit Config). Формат в обоих случаях один:

{
  "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"]

Заметка для контрибьюторов

Двухфазный паттерн живёт в stage(), redeem() и _expire(). Если добавляете инструментам с побочными эффектами, используйте его.

Одна тонкость имеет значение: redeem() не расходует токен, когда тип инструмента не совпал. Модель, случайно позвонившая не того инструмента, не должна ждать одобрения пользователя и принуждать повторно подтверждать всё сначала. Это был настоящий баг, пойманный в тестах.

Новые серверы возможностей должны быть такой же формы — один файл, один домен, чтение равнопаправное, запись gated, отказ при выходе за рамки, а не подтверждение.

Статус

На раннем этапе. Сервер projects протестирован и используется ежедневно; планируются другие серверы возможностей (media, mail, browser) в рамках более крупного voice-assistant. Issues и PRWelcome.

Лицензия

MIT