Skip to main content
Glama
deenesjakoruzh
baalimago

slivingdoc

by baalimago
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Hybrid

테스트 커버리지: 83.7% 😍👌

slivingdoc 배너

기능

  • Git과 유사한 의미론: slivingdoc는 우리(와 에이전트)가 모두 알고 있는 용어를 사용하며, 사용 편의성을 위해 설계되었습니다.

  • 자동 충돌 해결: 두려움 없이 커밋하세요. 모든 충돌이 수락되기 전에 반드시 해결되어야 함을 신뢰하세요.

  • 고속 처리: 솔루션은 개념적으로 매우 간단하여, 매우 높은 확장성과 병렬 처리를 가능하게 합니다.

  • 플러그 앤 플레이: 버킷을 설정하고, 그것을 가리키고, 노트 동기화를 시작하세요!

docs/slivingdoc-v1.md는 이러한 보장 뒤에 있는 완전히 수락된 계약서입니다.

Related MCP server: Cellar

시작하기

에이전트 하네스에 추가하세요:

{
  "mcpServers": {
    "slivingdoc": {
      "command": "npx",
      "args": [
        "-y",
        "slivingdoc",
        "serve",
        "--bucket",
        "my-notes",
        "--workspace-root",
        "/srv/notes"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "<your-access-key-id>",
        "AWS_SECRET_ACCESS_KEY": "<your-secret-access-key>",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

버킷이 존재해야 하며, 자격 증명은 일반 AWS 체인에서 가져옵니다. 아직 S3 계정이 없으신가요? examples/seaweedfs/는 단계별 안내와 함께 로컬 SeaweedFS 컨테이너를 실행합니다. 또한 GitHub 릴리스에서 네이티브 바이너리를 직접 다운로드하여 (slivingdoc-v<semver>-<os>-<arch>) 그 자리에서 실행할 수 있습니다.

지원 플랫폼: Linux (amd64, 32-bit ARMv7, arm64), macOS (amd64, arm64), Windows (amd64). 32비트 Linux ARM 아티팩트는 Raspberry Pi OS armhf를 지원합니다.

작동 방식

서버는 stdio를 통해 두 개의 MCP 도구를 노출합니다:

도구

입력

성공 결과

notes_pull

path

OK

notes_commit

path, message

OK

notes_pull은 현재 노트북을 디렉토리에 씁니다. notes_commit은 변경 사항을 게시하고 동시에 충돌하지 않는 변경 사항을 통합합니다. 호출 사이에는 프로토콜이 전혀 없습니다. 에이전트는 이미 가지고 있는 도구로 파일을 편집하고, 인간은 모든 편집기로 동일한 디렉토리에 쓸 수 있습니다. 다음 커밋은 그들의 변경 사항도 전달합니다.

인간은 MCP 호스트 없이도 두 작업을 직접 수행할 수 있습니다. 상대 경로는 작업 디렉토리를 기준으로 확인됩니다:

slivingdoc pull notes
# edit UTF-8 text files under notes/
slivingdoc commit notes -m "meeting summary"

성공 시 통합 결과 보고서가 출력됩니다: OK 상태, 수락된 원격 생성, 파일별 삽입 및 삭제 수, 총계 요약. 도메인 오류는 0이 아닌 종료 코드와 함께 솔직한 보고서를 출력합니다: 오류 범주, 재시도 가능 여부, 충돌이 발생한 각 파일과 해당 라인 범위. 색상은 실제 터미널에서만 나타나며, 비어 있지 않은 NO_COLOR에 의해 비활성화됩니다.

Git 부분

모든 에이전트가 동시에 쓰도록 두면 작동하겠지만, 경쟁 조건에 압도될 것입니다. 따라서 slivingdoc는 libgit2를 통해 내장된 Git을 가지고 있으며, 효과적으로 다음을 수행합니다:

  1. git pull

  2. (잠재적 충돌 해결 로컬에서)

  3. git add .

  4. git commit -m "<agent message>"

  5. git push

  6. (잠재적 충돌 해결 로컬에서)

이 모든 Git 작업은 노트 디렉토리의 개인 미러 내에서 로컬로 처리되어 "간소화된" Git 시퀀스를 남깁니다. 이는 두 가지 절충 덕분에 작동합니다. 첫째, 로컬 노트 디렉토리는 notes_pull 시 변경되기 쉬우며, 원격 상태에 우선권이 있어 충돌 표시를 남깁니다. 둘째, 시스템은 텍스트(깨끗한 UTF-8)에만 작동합니다.

구성

serve, pull, commit은 동일한 플래그와 환경 변수를 읽습니다. --bucket은 필수입니다. 가장 일반적인 플래그:

플래그

환경 변수

기본값

--bucket

SLIVINGDOC_BUCKET

— (필수)

--workspace-root

SLIVINGDOC_WORKSPACE_ROOT

시작 시 작업 디렉토리

--endpoint

AWS_ENDPOINT_URL_S3

AWS 확인

--region

AWS_REGION

us-east-1

slivingdoc serve -h는 전체 참조를 출력하며, docs/running.md는 운영자에게 필요한 모든 것을 다룹니다: 모든 플래그, 정확한 S3 권한, 로깅(stderr의 LOG_LEVEL), 노트북 규칙, 충돌 복구, 체크포인트 보존. terraform/의 Terraform 모듈은 하나의 노트북을 위한 버킷과 최소 권한 IAM 사용자를 프로비저닝합니다.

개발

  • AGENTS.md — 개발자 및 에이전트 가이드: 패키지 맵, 작업 흐름, 규칙, QA 게이트.

  • docs/slivingdoc-v1.md — 수락된 아키텍처 계약서.

  • docs/build.md — 고정된 libgit2 소스부터 종속성 검사까지의 네이티브 빌드.

  • docs/testing.md — 테스트 명령, 테스트 계층, 라이브 AWS 없음 규칙.

  • docs/releasing.md — 릴리스 아티팩트, npm 신뢰할 수 있는 게시, make release.

make qa #lint plus the full Go and npm test suites

라이선스

MIT — LICENSE를 참조하세요. 정적으로 링크된 libgit2에 대한 타사 고지는 NOTICE에 있습니다.

Paris Hilton과 관련 없음.

Available Tools

2 tools
notes_commitA

Publish the caller's changes in the notebook directory and incorporate concurrent non-conflicting changes. Omit path or pass an empty string to use the server's notebook directory, which the result reports. message must be non-blank UTF-8 without U+0000, at most 16,384 bytes; it is retained in recent internal history only.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoOptional absolute UTF-8 host path of the notebook directory, 1 through 4,096 bytes. Omit it or pass an empty string to use the server's notebook directory.
messageYesCommit message: non-blank UTF-8 without U+0000, at most 16,384 bytes.

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It does add real behavioral context beyond the name: default-path fallback, merge semantics for concurrent non-conflicting changes, and the notable fact that the message is retained only in recent internal history. However, it says nothing about permissions, failure/conflict behavior, or reversibility for what is effectively a mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and scope, followed by the constraints. The dense run of message constraints is necessary detail, though it makes the second sentence slightly overloaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with no annotations and no output schema, the definition covers the default path, the merge behavior, and the message rules, and notes that the resolved directory is reported in the result. Error and conflict-resolution outcomes remain unstated, a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning the schema lacks: the message's limited retention in internal history, and that the resolved notebook directory comes back in the result. These clarify semantics rather than restating constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (publish changes in the notebook directory) and adds the merge scope (incorporate concurrent non-conflicting changes). It never names the sibling notes_pull, so an agent must infer the pairing from the name alone, which keeps it short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can guess this is the write-side counterpart to notes_pull, but the description never says when to commit versus pull, nor any prerequisite such as needing local changes first. Minimum viable guidance, no explicit when/when-not.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

notes_pullA

Write the current notebook into the notebook directory and record the accepted state. Omit path or pass an empty string to use the server's notebook directory, which the result reports. Edit UTF-8 text files (without U+0000) there between notes_pull and notes_commit; notes_commit publishes the changes and incorporates concurrent non-conflicting changes.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoOptional absolute UTF-8 host path of the notebook directory, 1 through 4,096 bytes. Omit it or pass an empty string to use the server's notebook directory.

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full load and does disclose meaningful behavior: the path-default rule, the UTF-8/no-U+0000 constraint on editable files, the accepted-state recording, and that notes_commit merges concurrent non-conflicting changes. It omits whether existing local files are overwritten or what permissions are required, which a mutation-adjacent tool would ideally state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with the primary action front-loaded and the default-behavior detail immediately after. Dense but every clause carries information; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-optional-parameter tool with no annotations and no output schema, the description covers the default path, the edit window, file-format constraints, and the sibling's role. Return values are only partially addressed (it notes the result reports the directory), which keeps it from a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single path parameter is fully documented there, including the 1–4,096 byte range. The description only restates the omit/empty-string default and adds that the result reports the directory, so baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action (materialize the current notebook into a notebook directory and record the accepted state) and clearly distinguishes itself from the sibling notes_commit, which 'publishes the changes.' The phrasing 'write the current notebook into the notebook directory' is slightly ambiguous about data direction, but the pull/commit pairing makes the intent recoverable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit workflow: edit the UTF-8 files 'between notes_pull and notes_commit,' with notes_commit handling publication and merge. It does not state when not to use it (e.g. if local edits already exist) or what happens on re-pull, so it stops short of full when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observednotes_commit
    • First observednotes_pull
Deploy Server
Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

A3.7/5.0

Scored across 2 tools

Disambiguation5/5

notes_commit and notes_pull have clearly distinct purposes: one publishes local changes and incorporates concurrent changes, the other writes the current notebook into the directory. Their descriptions make the boundary unambiguous.

Naming Consistency5/5

Both tools follow a consistent notes_<verb> snake_case pattern. There are no deviations or mixed conventions.

Tool Count3/5

With only two tools, the set is borderline thin for a notebook version control system. While each tool earns its place, typical workflows require more operations.

Completeness2/5

The toolset covers only pull and commit, missing critical operations such as conflict resolution, status, history, and initialization. These significant gaps will cause agent failures in realistic use.

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Git MCP Server

    a-g-e-n-t-s
    A
    license
    Not graded
    quality
    D
    maintenance
    A secure and scalable Git MCP server giving AI agents powerful version control for local and (soon) serverless environments.
    91 npm
    Apache 2.0

  • Cellar

    fbereilh
    A
    license
    Not graded
    quality
    A
    maintenance
    An interactive notebook server that enables humans and AI agents to collaboratively edit and run Jupyter notebooks on a shared kernel, with real-time streaming and automatic MCP integration for agent access.
    18 npm
    MIT

  • git-courer

    blak0p
    A
    license
    Not graded
    quality
    A
    maintenance
    An MCP server that gives AI agents a full, safe interface to Git with automatic backups, isolated worktrees, and structured JSON outputs.
    43
    MIT