Skip to main content
Glama
deenesjakoruzh
baalimago

slivingdoc

by baalimago
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Hybrid

テストカバレッジ: 83.7% 😍👌

slivingdoc banner

機能

  • 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ビットARMv7, arm64), macOS (amd64, arm64), Windows (amd64)。32ビットLinux ARMアーティファクトはRaspberry Pi OS armhfをサポートします。

仕組み

サーバーはstdioを介して2つの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 ステータス、受け入れられたリモート世代、ファイルごとの挿入および削除カウント、および合計トレーラーです。ドメインエラーが発生した場合、ゼロ以外で終了し、率直なレポート（エラーカテゴリ、再試行可能な判定、競合した各ファイルとその行範囲）を出力します。色は実際のターミナルでのみ表示され、空でない 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シーケンスを残します。これは2つの妥協点により機能します。第一に、ローカルノートディレクトリは 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モジュールは、1つのノートブック用にバケットと最小権限の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