filekeeper-mcp 0.1.0__tar.gz

filekeeper_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sangingeum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

filekeeper_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: filekeeper-mcp
+Version: 0.1.0
+Summary: MCP server that exposes Filekeeper's filesystem operations to agent hosts.
+Keywords: filesystem,mcp,agents,atomic-write
+Author: sangingeum
+Author-email: sangingeum <sangingeum@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Filesystems
+Requires-Dist: filekeeper-cli>=0.1,<0.2
+Requires-Dist: mcp>=2.3,<3
+Requires-Python: >=3.12, <3.13
+Project-URL: Homepage, https://github.com/sangingeum/filekeeper
+Project-URL: Changelog, https://github.com/sangingeum/filekeeper/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# filekeeper-mcp
+
+The Model Context Protocol server for [Filekeeper](../..). It is a thin adapter:
+every tool delegates to the `filekeeper` Core library, so an operation behaves
+identically whether it arrives through the CLI or through MCP.
+
+This is a **separate distribution**. `pip install filekeeper-cli` installs only
+Core and the `keeper` CLI and never pulls the MCP SDK. `pip install
+filekeeper-mcp` installs both.
+
+## Install and run
+
+```bash
+uv tool install filekeeper-mcp     # or: pip install filekeeper-mcp
+filekeeper-mcp --root ~/project
+```
+
+The transport is STDIO. There is no network listener in this release, and no
+option that binds a socket.
+
+Start-up options:
+
+| Option | Meaning |
+| ------ | ------- |
+| `--workspace NAME` | serve a registered workspace by name or id |
+| `--root PATH` | serve a directory as a transient workspace (nothing registered) |
+| `--home PATH` | Filekeeper home directory; defaults to `FILEKEEPER_HOME` or the user data dir |
+| `--actor NAME` | identity recorded on every mutation (optional audit metadata) |
+| `--task-id ID` | optional external task identifier recorded on every mutation |
+| `--log-level LEVEL` | `debug`, `info`, `warning` (default), `error`, `critical`; stderr only |
+
+`--workspace` and `--root` are mutually exclusive. Selection precedence is the
+same as the CLI: explicit name, explicit root, then the configured default, then
+the single registered workspace. The server never guesses between several.
+
+Allowed roots come from start-up configuration only. No tool argument can widen
+the workspace, register a workspace, or point the server at another tree.
+
+Example host configuration:
+
+```json
+{
+  "mcpServers": {
+    "filekeeper": {
+      "command": "filekeeper-mcp",
+      "args": ["--root", "/home/me/project", "--actor", "editor"]
+    }
+  }
+}
+```
+
+## Tools
+
+Read-only:
+
+`workspace_list`, `workspace_info`, `file_read`, `file_read_many`,
+`directory_list`, `file_info`, `file_search`, `content_search`, `history_list`,
+`history_get`, `history_diff`.
+
+Mutating:
+
+`file_create`, `file_write`, `file_copy`, `file_move`, `file_delete`,
+`directory_create`, `directory_delete`, `file_replace_text`,
+`file_replace_lines`, `file_insert_lines`, `file_delete_lines`,
+`file_apply_patch`, `undo_operation`, `undo_last`.
+
+Conventions that hold for every tool:
+
+- Paths are workspace-relative. Absolute paths are accepted only when they
+  resolve inside the selected workspace.
+- Line numbers are **1-based and inclusive**. Out-of-range references are
+  refused, never clamped. End-of-file insertion is `position: "end"`.
+- Every mutating tool returns the Core `operation_id` and `undo_available`.
+  `operation_id` is `null` for a dry run.
+- `expected_hash` (whole file, from `file_info` or `file_read`) and
+  `expected_content` (the exact text of the edited region) are the guards. Pass
+  at least one on content you did not just read.
+- `dry_run` validates every guard and writes nothing. It is available on every
+  mutating tool.
+- `file_replace_text` requires an explicit `match` policy, `"first"` or `"all"`,
+  and reports the matching stage (`exact` or `normalised`) in its result.
+- `i_accept_secret_write_risk` is the only way past the credential-shaped write
+  refusal. The override records a warning in the result.
+- Destructive tools (`file_delete`, `directory_delete`, `file_apply_patch` and
+  the no-undo-free content replacements) state their scope in their description
+  and never operate outside the selected root. Recursive directory deletion
+  requires both `recursive` and `confirm_recursive`.
+
+Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`,
+`idempotentHint`, `openWorldHint`) that describe what it actually does. A whole
+file write is not read-only and not idempotent; a directory create is additive;
+readers are read-only and idempotent.
+
+## Limits
+
+The adapter refuses oversized requests instead of truncating them silently:
+
+| Bound | Value |
+| ----- | ----- |
+| paths in `file_read_many` | 32 |
+| patch size | 1 MiB |
+| requested search results | 200 |
+| requested directory entries | 1000 |
+| requested history entries | 200 |
+
+Core's own configurable limits (`max_read_bytes`, `max_write_bytes`,
+`max_search_results`, `max_directory_entries`, `max_recursion_depth`) still
+apply and are described in the main README. A bounded result reports
+`truncated` rather than pretending to be complete.
+
+## Errors
+
+Failures are structured data, never a stack trace:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "CONTENT_CONFLICT",
+    "message": "file content changed since it was read; refusing to overwrite",
+    "retryable": false,
+    "details": {
+      "path": "notes.txt",
+      "expected_hash": "sha256:...",
+      "actual_hash": "sha256:...",
+      "recovery": "re-read the target, then retry against its current hash"
+    }
+  }
+}
+```
+
+The envelope is the same one the CLI emits: a failure document has exactly `ok`
+and `error` at the top level, and `error` has exactly `code`, `message`,
+`retryable` and `details`. The caller's own path is in `error.details.path`;
+server-side host paths are not preserved. `retryable` describes the identical
+request, so a stale hash is `false`: the caller must re-read the target and write
+against its current hash.
+
+## Not in this release
+
+Advisory locks, user-facing snapshots and restore, batch execution, file
+watching, HTTP transport, redo, and binary/media reads are deferred. They are not
+half-implemented and not advertised as tools.
+
+## Dependency pin
+
+The server is built and tested against `mcp>=2.3,<3`. The SDK's server API
+changed between 1.x and 2.x, so the major version is pinned; see
+`docs/decisions.md` in the repository for the reasoning.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

filekeeper_mcp-0.1.0/README.md

@@ -0,0 +1,153 @@
+# filekeeper-mcp
+
+The Model Context Protocol server for [Filekeeper](../..). It is a thin adapter:
+every tool delegates to the `filekeeper` Core library, so an operation behaves
+identically whether it arrives through the CLI or through MCP.
+
+This is a **separate distribution**. `pip install filekeeper-cli` installs only
+Core and the `keeper` CLI and never pulls the MCP SDK. `pip install
+filekeeper-mcp` installs both.
+
+## Install and run
+
+```bash
+uv tool install filekeeper-mcp     # or: pip install filekeeper-mcp
+filekeeper-mcp --root ~/project
+```
+
+The transport is STDIO. There is no network listener in this release, and no
+option that binds a socket.
+
+Start-up options:
+
+| Option | Meaning |
+| ------ | ------- |
+| `--workspace NAME` | serve a registered workspace by name or id |
+| `--root PATH` | serve a directory as a transient workspace (nothing registered) |
+| `--home PATH` | Filekeeper home directory; defaults to `FILEKEEPER_HOME` or the user data dir |
+| `--actor NAME` | identity recorded on every mutation (optional audit metadata) |
+| `--task-id ID` | optional external task identifier recorded on every mutation |
+| `--log-level LEVEL` | `debug`, `info`, `warning` (default), `error`, `critical`; stderr only |
+
+`--workspace` and `--root` are mutually exclusive. Selection precedence is the
+same as the CLI: explicit name, explicit root, then the configured default, then
+the single registered workspace. The server never guesses between several.
+
+Allowed roots come from start-up configuration only. No tool argument can widen
+the workspace, register a workspace, or point the server at another tree.
+
+Example host configuration:
+
+```json
+{
+  "mcpServers": {
+    "filekeeper": {
+      "command": "filekeeper-mcp",
+      "args": ["--root", "/home/me/project", "--actor", "editor"]
+    }
+  }
+}
+```
+
+## Tools
+
+Read-only:
+
+`workspace_list`, `workspace_info`, `file_read`, `file_read_many`,
+`directory_list`, `file_info`, `file_search`, `content_search`, `history_list`,
+`history_get`, `history_diff`.
+
+Mutating:
+
+`file_create`, `file_write`, `file_copy`, `file_move`, `file_delete`,
+`directory_create`, `directory_delete`, `file_replace_text`,
+`file_replace_lines`, `file_insert_lines`, `file_delete_lines`,
+`file_apply_patch`, `undo_operation`, `undo_last`.
+
+Conventions that hold for every tool:
+
+- Paths are workspace-relative. Absolute paths are accepted only when they
+  resolve inside the selected workspace.
+- Line numbers are **1-based and inclusive**. Out-of-range references are
+  refused, never clamped. End-of-file insertion is `position: "end"`.
+- Every mutating tool returns the Core `operation_id` and `undo_available`.
+  `operation_id` is `null` for a dry run.
+- `expected_hash` (whole file, from `file_info` or `file_read`) and
+  `expected_content` (the exact text of the edited region) are the guards. Pass
+  at least one on content you did not just read.
+- `dry_run` validates every guard and writes nothing. It is available on every
+  mutating tool.
+- `file_replace_text` requires an explicit `match` policy, `"first"` or `"all"`,
+  and reports the matching stage (`exact` or `normalised`) in its result.
+- `i_accept_secret_write_risk` is the only way past the credential-shaped write
+  refusal. The override records a warning in the result.
+- Destructive tools (`file_delete`, `directory_delete`, `file_apply_patch` and
+  the no-undo-free content replacements) state their scope in their description
+  and never operate outside the selected root. Recursive directory deletion
+  requires both `recursive` and `confirm_recursive`.
+
+Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`,
+`idempotentHint`, `openWorldHint`) that describe what it actually does. A whole
+file write is not read-only and not idempotent; a directory create is additive;
+readers are read-only and idempotent.
+
+## Limits
+
+The adapter refuses oversized requests instead of truncating them silently:
+
+| Bound | Value |
+| ----- | ----- |
+| paths in `file_read_many` | 32 |
+| patch size | 1 MiB |
+| requested search results | 200 |
+| requested directory entries | 1000 |
+| requested history entries | 200 |
+
+Core's own configurable limits (`max_read_bytes`, `max_write_bytes`,
+`max_search_results`, `max_directory_entries`, `max_recursion_depth`) still
+apply and are described in the main README. A bounded result reports
+`truncated` rather than pretending to be complete.
+
+## Errors
+
+Failures are structured data, never a stack trace:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "CONTENT_CONFLICT",
+    "message": "file content changed since it was read; refusing to overwrite",
+    "retryable": false,
+    "details": {
+      "path": "notes.txt",
+      "expected_hash": "sha256:...",
+      "actual_hash": "sha256:...",
+      "recovery": "re-read the target, then retry against its current hash"
+    }
+  }
+}
+```
+
+The envelope is the same one the CLI emits: a failure document has exactly `ok`
+and `error` at the top level, and `error` has exactly `code`, `message`,
+`retryable` and `details`. The caller's own path is in `error.details.path`;
+server-side host paths are not preserved. `retryable` describes the identical
+request, so a stale hash is `false`: the caller must re-read the target and write
+against its current hash.
+
+## Not in this release
+
+Advisory locks, user-facing snapshots and restore, batch execution, file
+watching, HTTP transport, redo, and binary/media reads are deferred. They are not
+half-implemented and not advertised as tools.
+
+## Dependency pin
+
+The server is built and tested against `mcp>=2.3,<3`. The SDK's server API
+changed between 1.x and 2.x, so the major version is pinned; see
+`docs/decisions.md` in the repository for the reasoning.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

filekeeper_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "filekeeper-mcp"
+version = "0.1.0"
+description = "MCP server that exposes Filekeeper's filesystem operations to agent hosts."
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "filesystem",
+    "mcp",
+    "agents",
+    "atomic-write",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Filesystems",
+]
+dependencies = [
+    "filekeeper-cli>=0.1,<0.2",
+    "mcp>=2.3,<3",
+]
+
+[[project.authors]]
+name = "sangingeum"
+email = "sangingeum@gmail.com"
+
+[project.scripts]
+filekeeper-mcp = "filekeeper_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/sangingeum/filekeeper"
+Changelog = "https://github.com/sangingeum/filekeeper/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "filekeeper_mcp"
+module-root = "src"
+
+[tool.uv.sources.filekeeper-cli]
+workspace = true

filekeeper_mcp-0.1.0/pyproject.toml.orig

@@ -0,0 +1,43 @@
+[project]
+name = "filekeeper-mcp"
+version = "0.1.0"
+description = "MCP server that exposes Filekeeper's filesystem operations to agent hosts."
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "sangingeum", email = "sangingeum@gmail.com" }]
+keywords = ["filesystem", "mcp", "agents", "atomic-write"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Filesystems",
+]
+dependencies = [
+    "filekeeper-cli>=0.1,<0.2",
+    # Pinned to the major version this server was built and tested against. The
+    # SDK's server API changed between 1.x and 2.x; see docs/decisions.md.
+    "mcp>=2.3,<3",
+]
+
+[project.scripts]
+filekeeper-mcp = "filekeeper_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/sangingeum/filekeeper"
+Changelog = "https://github.com/sangingeum/filekeeper/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "filekeeper_mcp"
+module-root = "src"
+
+[tool.uv.sources]
+filekeeper-cli = { workspace = true }

filekeeper_mcp-0.1.0/src/filekeeper_mcp/__init__.py

@@ -0,0 +1,13 @@
+"""MCP protocol adapter over Filekeeper Core.
+
+This package contains no filesystem logic. Every operation is delegated to
+``filekeeper.core``; the adapter only maps protocol arguments to Core calls and
+Core results to structured protocol results. Core remains importable without the
+MCP SDK installed.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

filekeeper_mcp-0.1.0/src/filekeeper_mcp/errors.py

@@ -0,0 +1,115 @@
+"""Structured protocol errors.
+
+Every failure reaches the client as data, never as a Python traceback. The Core
+error code and the caller's own path survive; host filesystem paths do not. A
+resolved host path is useful to nobody outside this machine and can leak the shape
+of the tree the server is confined to.
+
+The envelope is the same one the CLI emits: ``{"ok": false, "error": {...}}``
+with no fields beside ``ok`` and ``error`` at the top level. The caller's path
+travels inside ``error.details.path``, where Core already records it.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from typing import Any
+
+import mcp.types as types
+
+from filekeeper import ErrorCode, FilekeeperError
+
+from .payloads import compact_json
+
+# Path-like strings that begin a token. Relative paths such as ``src/main.py`` are
+# left alone because the character before the slash is part of a word.
+_ABSOLUTE_POSIX = re.compile(r"(?<![\w:/])/(?:[^\s\"',;:()\[\]]+)")
+_ABSOLUTE_WINDOWS = re.compile(r"\b[A-Za-z]:\\[^\s\"',;:()\[\]]+")
+
+# Detail keys that only ever carry a server-side location.
+_LOCATION_KEYS = frozenset({"root", "state_dir", "home", "database", "path_absolute"})
+
+
+def scrub_text(text: str, host_paths: Iterable[str]) -> str:
+    """Remove host locations from a message while keeping its meaning."""
+
+    cleaned = text
+    for location in sorted(host_paths, key=len, reverse=True):
+        if location:
+            cleaned = cleaned.replace(location, "<host-path>")
+    cleaned = _ABSOLUTE_WINDOWS.sub("<host-path>", cleaned)
+    return _ABSOLUTE_POSIX.sub("<host-path>", cleaned)
+
+
+def _scrub_value(value: Any, host_paths: Iterable[str]) -> Any:
+    if isinstance(value, str):
+        return scrub_text(value, host_paths)
+    if isinstance(value, dict):
+        return {str(key): _scrub_value(item, host_paths) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_scrub_value(item, host_paths) for item in value]
+    return value
+
+
+def error_payload(
+    error: FilekeeperError,
+    *,
+    host_paths: Iterable[str],
+    caller_path: str | None = None,
+) -> dict[str, Any]:
+    """The stable error envelope: ``ok`` plus ``error.code/message/retryable/details``.
+
+    Nothing is duplicated at the top level: a client reads every error the same
+    way it reads a CLI JSON error.
+    """
+
+    locations = tuple(host_paths)
+    details = {
+        key: _scrub_value(value, locations)
+        for key, value in error.details.items()
+        if key not in _LOCATION_KEYS
+    }
+    error_body: dict[str, Any] = {
+        "code": str(error.code),
+        "message": scrub_text(error.message, locations),
+        "retryable": error.retryable,
+    }
+    if caller_path is not None:
+        details.setdefault("path", caller_path)
+    if details:
+        error_body["details"] = details
+    return {"ok": False, "error": error_body}
+
+
+def error_result(
+    error: FilekeeperError,
+    *,
+    host_paths: Iterable[str],
+    caller_path: str | None = None,
+) -> types.CallToolResult:
+    payload = error_payload(error, host_paths=host_paths, caller_path=caller_path)
+    return types.CallToolResult(
+        content=[types.TextContent(type="text", text=compact_json(payload))],
+        structured_content=payload,
+        is_error=True,
+    )
+
+
+def internal_error_result() -> types.CallToolResult:
+    """A crash rendered as data. The exception text stays in the server log."""
+
+    error = FilekeeperError(
+        "the operation failed unexpectedly; nothing about the request was changed "
+        "beyond what an earlier partial result reported"
+    )
+    return error_result(error, host_paths=())
+
+
+__all__ = [
+    "ErrorCode",
+    "error_payload",
+    "error_result",
+    "internal_error_result",
+    "scrub_text",
+]

filekeeper_mcp-0.1.0/src/filekeeper_mcp/payloads.py

@@ -0,0 +1,55 @@
+"""Conversion of Core values into JSON-ready protocol payloads.
+
+Rendering only: nothing here reads, resolves or writes a filesystem path. The
+shapes deliberately mirror the Core dataclasses field for field, so a client sees
+exactly what the library returned.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+def jsonable(value: Any) -> Any:
+    """Convert dataclasses, enums, paths, tuples and mappings into JSON values."""
+
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {
+            field.name: jsonable(getattr(value, field.name))
+            for field in dataclasses.fields(value)
+        }
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, dict):
+        return {str(key): jsonable(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [jsonable(item) for item in value]
+    return value
+
+
+def success_payload(result: Any) -> dict[str, Any]:
+    """Wrap one Core result in the stable success envelope."""
+
+    payload: dict[str, Any] = {"ok": True}
+    converted = jsonable(result)
+    if isinstance(converted, dict):
+        payload.update(converted)
+    else:  # pragma: no cover - every tool result is an object
+        payload["result"] = converted
+    return payload
+
+
+def compact_json(payload: dict[str, Any]) -> str:
+    """The text content that accompanies structured content.
+
+    Kept compact on purpose: the structured payload is the contract, and this is
+    the fallback for hosts that only render text.
+    """
+
+    return json.dumps(jsonable(payload), ensure_ascii=False, separators=(",", ":"))