Repository navigation
CLI MCP server
baram mcp 는 명령줄 도구의 명령 함수를 MCP 도구로 내는 stdio 서버다 — 같은 실행 파일이 돌고, 같은 명령 함수를
부르는 둘째 앞단이다. 이 페이지는 MCP 서버의 결정과 불변식을 모으고, 명령줄과 같은 결정은 그 페이지를 가리킨다. 명령줄과 함께 쓰는
층은 Architecture, 도구의 파일 경계가 묻는 규칙은
Paths and vault boundary, 도구 오류 텍스트의 형식은
Output contract 가 답한다.
| 찾는 것 | 가는 곳 |
|---|---|
| 클라이언트 설정 · 도구 목록 · 페이지 · 명령줄과 다른 점 | 사용자 문서 |
| 무엇이 머지됐고 무엇이 남았나 · 남은 수동 확인 | 추적 이슈 |
| 코드가 지키는 계약 |
src-tauri/src/cli/mcp/ 의 모듈 헤더와 함수 · 타입의 문서 주석 |
클라이언트 ── stdin · stdout, 한 줄에 JSON-RPC 메시지 하나 ── baram mcp
│
▼
cli::run `mcp` 는 명령줄이 stdout 을 버퍼로 잡기 전에 갈라진다
▼
mcp::run --vault 마다 해석해 허용 집합을 고정한다. 실패하면 stdout 에 아무것도 쓰지 않고 끝난다
▼
rmcp 옛 핸드셰이크와 새 규격의 요청을 받는다
▼
Server::call_tool tools::call — 인자 표로 검사 → config.json 을 다시 읽기 → Scope::resolve 로 vault 하나
▼
cli::ops* 명령줄과 같은 명령 함수. backlinks · outgoing_links 는 IndexGate 안에서 돈다
▼
페이지 Page::cut, search 는 찾은 순서에서, read_note 는 줄로 — 결과는 structuredContent 와
같은 JSON 의 텍스트 블록으로 두 번 실린다
| 결정 | 근거 · 기각 |
|---|---|
| 도구는 명령줄 명령과 1:1 이고 명령줄의 명령 함수를 부른다 | 같은 함수를 부르므로 뜻이 하나다. 명령 함수와 다른 길은 둘이다 — read_note 는 노트만 받는 MCP 전용 짝 ops::read_note 를 부르고(파일을 읽는 read_text 는 read 와 함께 쓴다), --vault 를 주면 list_vaults 의 행은 Scope::rows 가 지어 앱이 등록하지 않은 --vault 의 unregistered 행을 더한다. list_tasks 의 file 과 outgoing_links 는 명령 함수 앞에서 노트 이름 규칙을 먼저 묻는다(아래 파일 경계). 결과 행은 --json 의 행 그대로이고, 페이지를 싣는 봉투 Page<T> 는 MCP 전용이다 — 명령줄의 봉투에 nextOffset 을 더하면 --json 의 공개 계약이 바뀐다. 도구 목록은 사용자 문서가 canonical 이다 |
| 도구만 내고, 도구마다 읽기 전용이라고 표시한다 | 설계 때의 문서 조사(2026-10-04)로는 네 클라이언트(Claude Code · Claude Desktop · Cursor · VS Code)가 모두 도구를 지원했고, 리소스 템플릿은 VS Code 에서만 확인됐다. readOnlyHint: true · openWorldHint: false 는 사실이다 — 쓰기 · 네트워크 · 디스크 캐시가 없다. 클라이언트는 이 표시를 보고 호출 전 확인을 건너뛸 수 있으므로, 다른 일을 하는 도구를 이 표시와 함께 더하지 않는다(catalog::definitions 의 문서 주석) |
--vault 는 허용 목록이다 — 여러 번 줄 수 있고 첫째가 기본값. 주지 않으면 그 호출 때 앱에 등록돼 있고 폴더가 있는 vault 와 폴더(vault::live) |
기본값만 정하고 범위를 좁히지 않으면 업무 vault 용으로 등록한 서버에서 모델이 다른 vault 를 읽는다. 앱에 등록되지 않은 폴더도 받는다 — 사용자가 클라이언트 설정에 적은 값이다. 기각: --vault 하나로 고정(vault 마다 서버를 따로 등록해야 한다), 기본값만 정하기 |
허용 집합과 그 등록 정보는 호출마다 config.json 에서 다시 읽는다 |
앱에서 vault 를 등록 · 해제 · 개명하면 다음 호출에 반영된다. --vault 를 주면 루트와 기본값은 시작 때 고정되고, 호출마다 다시 읽는 것은 그 루트의 등록 정보 — 이름 · 별칭, 앱이 그 루트를 등록한 경로 표기(#911 부터 경로 인자를 맞추는 표기의 하나), 앱이 그 루트를 등록하는지 — 다. 링크 인덱스도 호출마다 짓는다. 기각: 캐시 — 무효화 판정을 새로 들여야 한다 |
--vault 가 없을 때 기본 vault 는 CLAUDE_PROJECT_DIR(절대 경로일 때만)를 담은 등록 vault 나 폴더, 그런 것이 없으면 서버가 시작된 디렉터리를 담은 것이다 |
설계 때의 문서 조사(2026-10-04)로는 Claude Desktop 의 설정에 작업 디렉터리 필드가 없고, Claude Code 는 stdio 서버의 작업 디렉터리를 문서에 적지 않는 대신 CLAUDE_PROJECT_DIR 를 넘긴다. 그래서 시작 디렉터리는 정해지지 않은 것으로 보고(추론) 명시된 신호를 먼저 본다. 상대 경로인 CLAUDE_PROJECT_DIR 는 그 정해지지 않은 디렉터리를 기준으로 풀리므로 쓰지 않는다. 같은 이유로 도구의 vault 는 상대 경로를 받지 않고 .notes 같은 값은 이름이다 — 명령줄의 --vault 와 다른 형태 판정이다. 앱의 활성 vault 로 대체하지 않는다 |
| 허용 집합을 정할 때 승인 저장소(§329–§336)와 대조하지 않는다 | 명령줄과 같은 이유다 — Decisions and history 의 승인 저장소 결정. 서버는 이름을 경로로 풀 뿐 권한을 주지 않고, 범위는 사용자가 클라이언트 설정에 적은 --vault(주지 않으면 앱의 등록)가 정한다. 승인 기록은 설정과 함께 읽히지만, 쓰는 곳은 backlinks 가 앱처럼 vault 별칭을 셀 때뿐이다 |
프로토콜은 공식 Rust SDK rmcp 로 받고, 매크로는 켜지 않는다 |
rmcp 는 옛 규격(initialize 핸드셰이크)과 새 규격(요청마다 _meta)을 추가 코드 없이 받는다. 기각: 옛 규격만 직접 구현(새 규격만 말하는 클라이언트가 나오면 끊기고 규격 추적을 우리가 진다), 두 규격을 직접 구현(추적 부담은 같고 코드가 크다). 매크로를 켜지 않는 것은 인자를 손으로 읽기 때문이다(다음 줄) — 매크로가 주는 인자 추출과 스키마 생성을 쓰지 않고, 켜면 darling 의 두 번째 버전이 의존 트리에 들어온다 |
| 인자는 도구마다 표 하나에서 입력 스키마와 검사를 함께 짓는다 | 스키마와 검사가 어긋날 수 없다. 나쁜 인자는 인자 이름을 적은 INVALID_ARGUMENT 도구 오류가 되어 모델이 읽고 고친다. 기각: rmcp 의 Parameters<T>(serde 의 타입 오류 문구가 필드 이름을 싣지 않는다), 구조체에서 스키마를 생성하고 검사기가 그 모양을 다시 읽기 |
| 모델이 고칠 수 있는 실패는 도구 오류, 모르는 도구는 프로토콜 오류다 | 규격은 입력 검증 오류를 모델이 보고 고치도록 도구 실행 오류로 분류한다. 도구 오류(isError)의 텍스트는 명령줄이 텍스트 모드에서 stderr 에 쓰는 것과 같고(output::write_error), structuredContent 가 없다 — 출력 스키마는 성공의 모양이다. 모르는 도구는 rmcp 의 라우터가 답하는 것과 같은 -32602, 인자 탓이 아닌 내부 실패는 -32603 이다 |
페이지는 숫자 offset · limit 이다 |
규격에 도구 결과의 페이지 규약이 없다. 기각: 불투명 커서 — 호출 사이의 밀림을 알릴 수 있지만 v1 은 단순함을 골랐고, 밀릴 수 있다는 것을 서버 instructions 에 적는다. search 의 뒤 페이지 메모리를 고친 #911 도 커서를 기각했다 — 한 도구에서만 숫자 페이지를 뒤집게 된다 |
search 는 찾은 순서에서 자르고 그 페이지 안에서 정렬한다 |
정렬한 뒤에 자르면 Windows 에서 페이지 사이에 중복 · 누락이 생긴다 — 검색의 순서는 절대 경로 문자열의 정렬이라 구분자 \ 에서 출력 정렬과 갈린다. Unix 에서는 두 방식이 같은 답을 내므로, 순서는 순수 함수의 시험(a_page_is_cut_in_match_order_and_sorted_within_itself)이 고정한다. 앞 페이지의 일치는 미리보기 없이 세기만 한다(#911) |
search 는 일반 폴더 안의 숨은 .md 도 찾고, MCP 에서 따로 거르지 않는다 |
앱의 검색 함수 그대로다. 결과를 거르면 검색이 상한까지 찾은 뒤 줄어들어 페이지가 어긋난다. 그런 일치는 read_note 로 열 수 없다는 것을 도구 설명과 사용자 문서에 적는다 |
링크 인덱스를 짓는 두 도구는 서버 안의 잠금 하나로 하나씩 돈다 (IndexGate) |
rmcp 는 요청마다 task 를 띄우므로, 잠금이 없으면 동시에 온 두 backlinks 가 인덱스 둘을 함께 지어 메모리를 두 배로 쓴다. 시험은 지은 횟수가 아니라 동시에 도는 빌드의 최댓값을 센다 — 캐시가 없으니 지은 횟수는 잠금이 있든 없든 같다 |
결과는 structuredContent 와, 같은 JSON 의 텍스트 블록으로 두 번 싣는다 |
2025-11-25 규격은 출력 스키마와 structuredContent 의 루트를 객체로 제한하고, 텍스트 블록은 하위 호환을 위한 권고다. 도구마다 limit 의 기본값과 read_note 의 글자 상한 READ_NOTE_CHARS 는 두 벌을 합친 크기의 추정에서 정했다. limit 의 최대는 모델이 요청할 수 있는 천장이고, 그 예산 안의 페이지가 아니다. 실제 클라이언트가 무엇을 셌는지는 아래 절 |
출력 스키마를 옮기기 쉬운 꼴로 고쳐 낸다 (#876, catalog::portable) |
schemars 는 null 이 될 수 있는 필드를 type 배열로, 정수를 비표준 format(uint 등)과 함께 쓴다. MCP Inspector 의 엄격 검사는 앞의 것을 경고했고(한 스키마에 type 하나만 받는 방언으로 옮기는 클라이언트가 거절할 수 있다), Claude Code 는 뒤의 것을 모르는 format 으로 경고했다. 그래서 anyOf 로 바꾸고 정수의 format 을 뺀다. 대가로 uint32 · uint 가 뜻하던 상한이 빠진다 — format 은 annotation 이라 잰 두 클라이언트 모두 그 상한을 검사하지 않았다 |
instructions 와 도구 설명은 규칙만 싣는다 |
instructions 는 세션에 한 번 실리고 vault 는 호출 사이에 바뀔 수 있다 — 그래서 vault 이름 대신 허용 집합과 기본값의 규칙을 적고, 이름은 list_vaults 가 보인다. 도구 설명은 도구가 무엇을 하는지만 적고 모델이 할 일을 지시하지 않는다. instructions 의 길이는 Claude Code 가 보관하는 길이 아래로 instructions_fit_what_claude_code_keeps 가 묶는다 |
| 종단 시험은 빌드된 실행 파일에 JSON-RPC 줄을 직접 쓴다 |
rmcp 의 클라이언트로 시험하면 rmcp 를 rmcp 에 맞춰 보게 된다 |
명령줄에서 vault 밖 거절은 범위 규칙이지만, MCP 에서는 도구의 파일 경계다 — 인자를 사람이 아니라 모델이 고르고(셸이 없는 클라이언트도 있다), 모델은 노트 본문의 지시에 움직일 수 있다(Paths and vault boundary). 경계는 세 PR 에 걸쳐 지금의 모양이 됐다.
-
#873 — 도구의
vault인자는 허용 집합 안의 vault 만 받고, 집합 밖의 경로와 없는 경로에 같은 문구의VAULT_NOT_FOUND로 답한다. 서버가 디스크의 디렉터리 존재를 알려 주지 않게 하려는 것이다. 노트를 읽는 도구는 노트만 받는다 —.git/config같은 노트 아닌 파일을 모델에 열지 않게. -
#875 — 그 판정은
..를 접기 전에 디스크에 물었다.<dir>/..는<dir>가 있을 때만 풀려, 디스크에서 프로세스가 들어갈 수 있는 어디든 폴더가 있는지가 답으로 드러났다(리뷰가 빌드된 실행 파일로 재현)...를 글자로 먼저 접게 고쳤다. -
#911 — 디스크로 정규화한 뒤 비교하면, 정규화가 성공했다는 사실이 "그 링크가 있다" 는 답이다. 그래서
vault인자와 절대 경로 인자는 디스크에 묻기 전에 vault 의 표기(정규 경로 · 앱이 등록한 경로 · 경로로 준--vault)와 글자로 맞춘다. 모델은 서버가 아는 표기 말고는 물을 수 없고, Windows 의 UNC 경로도 디스크에 닿지 않는다(Windows 갈래는 std 소스를 읽어 세웠고, #911 은 Windows 에서 돌려 보지 않았다. #914 부터windowsCI 잡이 크레이트 시험을 Windows 에서 돌려, 접두를 그 호스트의 std 와 대조하는 시험과 드라이브 조각 · verbatim 루트 · 글자 비교의 시험이 거기서 돈다. UNC 경로가 그 호스트에 접속하지 않는다는 것을 묻는 시험은 없고, 종단 시험tests/mcp.rs는 Unix 전용이다). 루트 밖으로 나가는 상대 경로의..도 글자로 막고(절대 경로에서 막은 신호로 돌아가는 길이었다), 노트 도구는 노트 이름 규칙을 파일이 있는지보다 먼저 묻는다.- 기각: MCP 에서 절대 경로 인자를 받지 않기 — Claude Code 가 작업 디렉터리의 절대 경로를 넘기는 쓰임을 막는다.
- 대가: 링크 ·
/tmp대/private/tmp· 대소문자만 다른 표기(Windows 에서는 ASCII 대소문자를 접는다)로 vault 를 고르던 사용이 거절된다 — 그 표기를 앱에 등록하거나--vault로 주면 받는다. 명령줄은 그대로 디스크에서 판정하고, 두 앞단을 가르는 것은Vault::spellings(명령줄은None)다. - 같은 PR 에서 닿지 못하는
--vault는IO가 됐지만, 도구의vault인자는 같은 문구로 남았다 — 집합 밖 폴더에 "닿지 못한다" 고 답하면 그 폴더가 있다는 것이 드러난다.
| 불변식 | 왜 · 무엇이 지키나 |
|---|---|
| stdout 은 프로토콜만 싣는다 | 섞인 한 줄은 클라이언트가 읽지 못하는 줄이다. 설정 경고는 stderr 로 — 시작 때 한 번, 그 뒤에는 목록이 바뀔 때만 쓴다(호출마다 다시 읽으므로 그대로 쓰면 같은 경고가 클라이언트 로그에 쌓인다). 종단 시험 stdout_carries_only_protocol_messages_when_the_config_warns
|
--vault 가 풀리지 않으면 stdout 에 아무것도 쓰지 않고, 명령줄과 같은 오류 · 종료 코드로 끝난다 |
클라이언트에는 서버가 뜨지 못한 것으로 보인다. 종단 시험 a_vault_flag_that_does_not_resolve_stops_the_server_before_stdout
|
클라이언트가 끝낸 세션은 종료 0 이다 — 핸드셰이크 전에 stdin 이 닫혀도 |
서버가 뜨는지만 확인하는 클라이언트가 그 길이다. 세션이 시작되지 못했거나 오류로 끝나면 stderr 한 줄과 종료 1. 종단 시험 closing_stdin_before_any_message_exits_0_and_writes_nothing · a_first_message_that_is_no_request_ends_the_server_with_exit_1
|
| 세션은 vault · 앱 설정 · 로그에 아무것도 쓰지 않는다 | 읽기 전용 표시가 사실이어야 한다. 종단 시험 a_session_writes_nothing_into_the_vault_the_config_or_the_logs 가 모든 도구를 부른 세션의 전후로 샌드박스 전체를 비교한다 |
| 새 도구는 이름 · 제목 · 설명 · 인자 · 출력 스키마 · 호출을 모두 얻어야 컴파일된다 |
ToolName 을 가르는 match 에 _ 갈래가 없다. 도구 순서 목록 ToolName::ALL 은 컴파일러가 보지 않는다 — tools/list 가 내는 이름은 종단 시험 tools_list_gives_the_nine_tools_of_the_spec 이 고정한다 |
-
src-tauri/Cargo.toml의rmcp요구는~다 — 같은 minor 안의 patch 를 따라간다. patch 가 동작을 바꾼 적이 있다: 핸드셰이크 전에_meta없는 요청을 거절한 뒤 3.5.0 은 세션을 끝냈고 3.5.1 은initialize를 이어 기다린다. 구현 계획 때 3.5.0 으로 한 프로브가 3.5.1 에서 틀렸다. - 그래서
rmcp가 정하는 동작 가운데 일부를 종단 시험이 고정한다 — 핸드셰이크 전의 거절 뒤에도 핸드셰이크가 되는 것 (a_request_before_the_handshake_is_refused_and_the_handshake_still_works), JSON 이 아닌 줄 뒤에도 세션이 사는 것 (a_line_that_is_not_json_leaves_the_session_open). 이 시험들은 우리 코드의 변이로는 빨개지지 않는다 —rmcp갱신을 감시하는 시험이다. -
serve의 주석은 한 버전의rmcp가 핸드셰이크 전에 메시지를 다루는 갈래를 순서대로 적는다. 새 버전에서도 맞는지는 소스를 비교해야 보인다 — minor 를 올린 #905 뒤에 #911 이 두 버전의 서버 핸드셰이크 코드를 소스로 비교했다. - 시험이 고정하지 않은
rmcp의 동작도 있다. 예: stdin 한 줄의 길이 상한 — 3.5 의 stdio 는 줄을 상한 없이 읽었고, #911 은 상한(3.6.0 부터)을 넘는 줄이 응답 없이 버려지고 서버가 다음 요청에 답하는 것을 손으로 확인했다.
2026-10-16, macOS 한 대에서 Claude Code 2.1.299(claude -p)와 MCP Inspector CLI 2.11.0 으로 쟀다. 다른 버전 · 계정 ·
대화형 세션에는 일반화하지 않는다.
- Claude Code 는 서버를 프로젝트 디렉터리에서 시작하고
CLAUDE_PROJECT_DIR를 넘겼다. 서버의 시작 디렉터리를 다른 vault 로 옮겨도 기본 vault 는 프로젝트 디렉터리를 담은 vault 였다 — 기본 vault 의 순서가 맞다는 확인이다. - Claude Code 는 결과의 두 벌 가운데 한 벌만 모델에 넘겼고, 결과를 그대로 넘기는 경계를 바이트가 아니라 글자로 셌다.
실제 vault 의 태스크를
list_tasks로 100 행씩 끝까지 잰 페이지는 가장 큰 것도 그대로 넘어간 결과보다 글자가 적었다 (그 페이지들을 Claude Code 에 보내지는 않았다). 그래서 기본limit을 낮추지 않았다 — 두 벌을 함께 센다고 본 설계 때의 추정으로는 상한을 넘는 페이지가 있었다. - 두 규격을 실제 클라이언트로 하나씩 확인했다 — Claude Code 는 그 계정에서 새 규격으로(배포가 단계적이라 계정마다 다를 수 있다), Inspector 는 옛 핸드셰이크로 붙었다.
남은 수동 확인은 추적 이슈 가 답한다.
-
서버를 끝낼 때 tokio 런타임을 떨어뜨리지 말 것. 떨어뜨리면 블로킹 스레드를 기다리는데,
tokio::io::stdin의 읽기는 대기 중이면 취소할 수 없다.mcp::run은shutdown_background()로 놓고 종료 코드를 돌려준다. -
clap 은 명령 이름 앞뒤에 나뉘어 적힌 전역 옵션의 한쪽 값만 남긴다.
mcp가--vault를 여럿 받게 되면서 리뷰가 찾았고, 기존 명령도--vault A files --vault B에서 A 를 조용히 버리고 있었다. 명령줄에 적힌--vault의 개수 (vault_flags)를 clap 이 남긴 개수와 비교해 사용법 오류로 거절한다(misuse). -
MCP 를 위해 명령줄과 함께 쓰는 함수의 순서를 바꾸지 말 것. 노트 이름 규칙을 먼저 묻는 순서는 MCP 전용 함수
(
paths::note_names_first)에 있다. 명령줄의note_arg순서를 바꾸면 노트가 아닌 없는 경로에 대한tasks --file·links의 종료 코드가1에서2로 바뀐다.
이 wiki 는 baram 리포의 wiki/ 에서
생성됩니다. 여기서 편집하지 마세요 — 다음 게시가 덮어씁니다. 고칠 것은 리포에 PR 로 보내 주세요.
링크 없는 항목은 아직 쓰지 않았다. 그 주제의 현재 출처는 해당 모듈의 헤더 주석이고, 어느 파일인지는 Code map 이, 구현 현황은 #298 · #372 가 답한다.
- Overview
- Architecture
- Core state machine — 미작성
- Adapters — 미작성
- Hangul and IME — 미작성
- Input islands and block entry
- Search — 미작성
- Source mode and code block CM
- Lifecycle and settings — 미작성
- WebKit selection churn
- PM machinery in non-editable views — 미작성
- Performance — 미작성
- Resource and security boundaries — 미작성
- Internal contracts — 미작성
- Command reference — 미작성
- Testing methodology — 미작성
- Code map
- Decisions and history
링크 없는 항목은 아직 쓰지 않았다. 쓰는 법은 사용자 문서 가,
구현 현황과 다음 단계는 추적 이슈 가, 계약은
src-tauri/src/cli/ 의 모듈 헤더와 함수 · 타입의 문서 주석이 답한다.
- Overview
- Architecture
- Vault resolution and app config — 미작성
- Paths and vault boundary
- Output contract
- Links and app parity
- MCP server
- Testing methodology — 미작성
- Code map — 미작성
- Decisions and history