otama

AI 어시스턴트 — Cursor, Claude Desktop 또는 직접 만든 음성 에이전트 — 가 로컬 git 저장소에 접근할 수 있게 해주는 MCP 서버입니다.

읽기 작업은 자유롭게 실행됩니다. 쓰기 작업은 항상 확인 토큰과 평이한 영어 요약을 먼저 반환하며, 해당 토큰으로 두 번째 호출되었을 때만 실제로 수행됩니다. 어시스턴트는 커밋하기 전에 사용자에게 허락을 구합니다.

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는 모델이 때때로 잘못 행동할 것임을 예상하고, 그로 인한 파급효과를 작게 만듭니다:

• 경로 샌드박스. 모든 경로는 설정된 루트(roots)에 대비해 검사되기 이전에 해석됩니다. .., 심볼릭 링크, 절대 경로는 샌드박스를 벗어날 수 없습니다.

• 2단계 확인. 토큰 없이 호출된 쓰기·실행 도구는 아무것도 하지 않고 무엇을 할지만 설명합니다. 토큰은 일회용이며, 2분 후 만료되고, 발급한 도구에 묶입니다.

• 명령 허용 목록. run_command는 허용 목록에 없는 명령은 확인을 묻지 않고 거부합니다. 잘못 알아들은 명령이 단 한 번의 "예"로 rm -rf로 이어지게 해서는 안 됩니다.

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(), _subscription()에 들어 있습니다. 사이드 이펙트가 있는 도구를 추가한다면 이 패턴을 사용하세요.

유지할 가치가 있는 세부 동작 하나: redeem()은 도구 종류가 일치하지 않으면 토큰을 소모하지 않습니다. 모델이 실수로 다른 도구를 호출했을 때 사용자의 승인을 소모하게 만들어 다시 같은 확인을 돌려받게 해서는 안 됩니다. 이것은 실제로 테스트에서 발견된 일반적인 버그였습니다.

새로운 능력(capability) 서버들도 같은 모양을 따랄 수 — 파일 하나, 도메인 하나, 읽기 도구 자유롭게, 쓰기 도구는 게이트에 묶이고, 어떤 행동이 범위를 벗어낸다면 확인을 구하는 것보다 거부해야 합니다.

상태

초기 단계입니다. projects 서버는 테스트를 거쳐 매일 사용 중이며, 미디어, 메일, 브라우저 등 더 많은 기능 서버를 업 군데 음성 어시스턴트 프로젝트의 일부로 계획하고 있습니다. 이슈와 PR 언제든 환영합니다.

라이선스

MIT.