scry-mcp 0.2.0__tar.gz

scry_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Michaelsen
+
+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.

scry_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: scry-mcp
+Version: 0.2.0
+Summary: Marker-indexed SQL cache MCP server
+Author-email: Patrick Michaelsen <michaelsenpatrick@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/prmichaelsen/scry
+Project-URL: Repository, https://github.com/prmichaelsen/scry
+Project-URL: Issues, https://github.com/prmichaelsen/scry/issues
+Keywords: mcp,sqlite,markers,indexing,claude,fts5
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development
+Classifier: Topic :: Database
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0
+Requires-Dist: watchdog>=4.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# scry
+
+Marker-indexed SQL cache MCP server. Scry indexes in-file `@scry.*` markers
+into a SQLite database that agents query via read-only SQL, providing
+structured project knowledge without LLM reasoning.
+
+[![PyPI](https://img.shields.io/pypi/v/scry-mcp.svg)](https://pypi.org/project/scry-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/scry-mcp.svg)](https://pypi.org/project/scry-mcp/)
+
+## Install
+
+```bash
+uv pip install scry-mcp
+# or:
+pip install scry-mcp
+```
+
+The PyPI distribution is `scry-mcp` (the bare name `scry` was already taken
+on PyPI). The import name and the installed console command are both
+`scry`.
+
+## Quickstart
+
+```bash
+# In your project root:
+scry init                # scaffolds agent/ + driver dirs, updates .gitignore
+```
+
+Then add it to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "scry": {
+      "command": "scry"
+    }
+  }
+}
+```
+
+The MCP client inherits cwd from wherever it's launched, and scry walks
+up from there looking for an `agent/` directory — so the same config
+works for any project. Bare `scry` (no subcommand) starts the MCP
+server over stdio — that's what Claude calls. Other subcommands:
+
+| Command | Purpose |
+|---|---|
+| `scry` | Run the MCP server (default). |
+| `scry init [path]` | Create `agent/` + `agent/drivers/@local/scry/{data,runtime,scripts}/` and a local `.gitignore` inside the driver dir. Idempotent — safe to run inside an ACP project. |
+| `scry surface [--force]` | One-shot batch reindex without booting the server. |
+| `scry version` | Print the package version. |
+
+The server walks up from `cwd` until it finds an `agent/` directory; that
+becomes the project root. The cache lives at
+`agent/drivers/@<namespace>/scry/data/project.db` and is gitignored.
+
+## Markers
+
+Scry recognizes five marker kinds. Block markers carry a YAML body between
+open/close tokens; line markers are single-line `@scry.<kind> <id> <ref>`.
+
+```html
+<!-- @scry.doc
+id: design.auth-flow~a1b2c3d4
+kind: design
+summary: >
+  JWT auth middleware, token validation, refresh flow
+status: active
+weight: 0.85
+tags: ["scope:auth", "topic:security"]
+rationale: >
+  Missing this causes auth bypass bugs
+applies: modifying auth, adding protected endpoints
+seeded_questions:
+  - How does token refresh work?
+@scry.doc.end -->
+
+<!-- @scry.file
+id: file.auth-middleware~e5f6a7b8
+kind: middleware
+summary: Express middleware that validates JWT on every request
+status: active
+weight: 0.7
+@scry.file.end -->
+
+<!-- @scry.anchor auth-check~f1e2d3c4
+description: JWT validation point for protected routes
+@scry.anchor.end -->
+```
+
+```python
+# @scry.impl validate-jwt~a1b2c3d4 spec.auth~xyz89012#FR3
+# @scry.test jwt-expiry~b2c3d4e5 spec.auth~xyz89012#UT1
+```
+
+Block markers can be embedded in any host-language comment style (HTML,
+Python, JS, JSDoc, Rust, bare YAML). Comment prefixes are inferred from
+the YAML body — there is no per-language config.
+
+## MCP tools
+
+| Tool | Purpose |
+|---|---|
+| `scry_sql(query)` | Read-only SQL gateway. Rejects mutator keywords. Returns `{results, row_count}` JSON. |
+| `scry_mint(kind, prefix)` | Generate a collision-free ID and the marker schema. |
+| `scry_surface(force=false)` | Batch reindex from disk. `force=true` hard-deletes records whose source file no longer exists. |
+| `scry_scrub()` | Create a `<branch>--clean` git branch with all `@scry.*` markers stripped and `agent/` removed. |
+| `scry_script(action, script?, params?)` | Discover and run validation scripts from `src/scry/scripts/` and `agent/drivers/@<ns>/scry/scripts/`. |
+
+## Database schema
+
+Five marker-backed tables (`scry__doc`, `scry__file`, `scry__anchor`,
+`scry__impl`, `scry__test`) plus `doc_relationship` (with cycle detection)
+and `migration`. FTS5 is maintained via triggers on the source tables —
+no manual rebuild step.
+
+The cache is fully reconstructable from disk via `scry_surface`. The DB is
+gitignored; after `git pull`, agents call `scry_surface` to rebuild.
+
+## Watcher
+
+A daemon thread runs alongside the MCP server, watching the project tree
+with a 150 ms debounce window. A lock file at
+`agent/drivers/@<ns>/scry/runtime/lock` performs PID-based primary
+election so multiple sessions don't race writes. The primary instance
+runs a cold scan on startup; secondaries observe and wait.
+
+On file deletion: docs and files are soft-deleted (`missing_since` set);
+anchors, impls, and tests are hard-deleted.
+
+## Tests
+
+```bash
+uv pip install -e ".[dev]"
+pytest
+```
+
+43 unit tests cover the parser, SQL gateway, mint, surface, watcher
+plumbing, script discovery, and relationship cycle detection.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

scry_mcp-0.2.0/README.md

@@ -0,0 +1,143 @@
+# scry
+
+Marker-indexed SQL cache MCP server. Scry indexes in-file `@scry.*` markers
+into a SQLite database that agents query via read-only SQL, providing
+structured project knowledge without LLM reasoning.
+
+[![PyPI](https://img.shields.io/pypi/v/scry-mcp.svg)](https://pypi.org/project/scry-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/scry-mcp.svg)](https://pypi.org/project/scry-mcp/)
+
+## Install
+
+```bash
+uv pip install scry-mcp
+# or:
+pip install scry-mcp
+```
+
+The PyPI distribution is `scry-mcp` (the bare name `scry` was already taken
+on PyPI). The import name and the installed console command are both
+`scry`.
+
+## Quickstart
+
+```bash
+# In your project root:
+scry init                # scaffolds agent/ + driver dirs, updates .gitignore
+```
+
+Then add it to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "scry": {
+      "command": "scry"
+    }
+  }
+}
+```
+
+The MCP client inherits cwd from wherever it's launched, and scry walks
+up from there looking for an `agent/` directory — so the same config
+works for any project. Bare `scry` (no subcommand) starts the MCP
+server over stdio — that's what Claude calls. Other subcommands:
+
+| Command | Purpose |
+|---|---|
+| `scry` | Run the MCP server (default). |
+| `scry init [path]` | Create `agent/` + `agent/drivers/@local/scry/{data,runtime,scripts}/` and a local `.gitignore` inside the driver dir. Idempotent — safe to run inside an ACP project. |
+| `scry surface [--force]` | One-shot batch reindex without booting the server. |
+| `scry version` | Print the package version. |
+
+The server walks up from `cwd` until it finds an `agent/` directory; that
+becomes the project root. The cache lives at
+`agent/drivers/@<namespace>/scry/data/project.db` and is gitignored.
+
+## Markers
+
+Scry recognizes five marker kinds. Block markers carry a YAML body between
+open/close tokens; line markers are single-line `@scry.<kind> <id> <ref>`.
+
+```html
+<!-- @scry.doc
+id: design.auth-flow~a1b2c3d4
+kind: design
+summary: >
+  JWT auth middleware, token validation, refresh flow
+status: active
+weight: 0.85
+tags: ["scope:auth", "topic:security"]
+rationale: >
+  Missing this causes auth bypass bugs
+applies: modifying auth, adding protected endpoints
+seeded_questions:
+  - How does token refresh work?
+@scry.doc.end -->
+
+<!-- @scry.file
+id: file.auth-middleware~e5f6a7b8
+kind: middleware
+summary: Express middleware that validates JWT on every request
+status: active
+weight: 0.7
+@scry.file.end -->
+
+<!-- @scry.anchor auth-check~f1e2d3c4
+description: JWT validation point for protected routes
+@scry.anchor.end -->
+```
+
+```python
+# @scry.impl validate-jwt~a1b2c3d4 spec.auth~xyz89012#FR3
+# @scry.test jwt-expiry~b2c3d4e5 spec.auth~xyz89012#UT1
+```
+
+Block markers can be embedded in any host-language comment style (HTML,
+Python, JS, JSDoc, Rust, bare YAML). Comment prefixes are inferred from
+the YAML body — there is no per-language config.
+
+## MCP tools
+
+| Tool | Purpose |
+|---|---|
+| `scry_sql(query)` | Read-only SQL gateway. Rejects mutator keywords. Returns `{results, row_count}` JSON. |
+| `scry_mint(kind, prefix)` | Generate a collision-free ID and the marker schema. |
+| `scry_surface(force=false)` | Batch reindex from disk. `force=true` hard-deletes records whose source file no longer exists. |
+| `scry_scrub()` | Create a `<branch>--clean` git branch with all `@scry.*` markers stripped and `agent/` removed. |
+| `scry_script(action, script?, params?)` | Discover and run validation scripts from `src/scry/scripts/` and `agent/drivers/@<ns>/scry/scripts/`. |
+
+## Database schema
+
+Five marker-backed tables (`scry__doc`, `scry__file`, `scry__anchor`,
+`scry__impl`, `scry__test`) plus `doc_relationship` (with cycle detection)
+and `migration`. FTS5 is maintained via triggers on the source tables —
+no manual rebuild step.
+
+The cache is fully reconstructable from disk via `scry_surface`. The DB is
+gitignored; after `git pull`, agents call `scry_surface` to rebuild.
+
+## Watcher
+
+A daemon thread runs alongside the MCP server, watching the project tree
+with a 150 ms debounce window. A lock file at
+`agent/drivers/@<ns>/scry/runtime/lock` performs PID-based primary
+election so multiple sessions don't race writes. The primary instance
+runs a cold scan on startup; secondaries observe and wait.
+
+On file deletion: docs and files are soft-deleted (`missing_since` set);
+anchors, impls, and tests are hard-deleted.
+
+## Tests
+
+```bash
+uv pip install -e ".[dev]"
+pytest
+```
+
+43 unit tests cover the parser, SQL gateway, mint, surface, watcher
+plumbing, script discovery, and relationship cycle detection.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

scry_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scry-mcp"
+version = "0.2.0"
+description = "Marker-indexed SQL cache MCP server"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Patrick Michaelsen", email = "michaelsenpatrick@gmail.com" }]
+keywords = ["mcp", "sqlite", "markers", "indexing", "claude", "fts5"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development",
+    "Topic :: Database",
+    "Topic :: Text Processing :: Indexing",
+]
+dependencies = [
+    "mcp>=1.0",
+    "watchdog>=4.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[project.urls]
+Homepage = "https://github.com/prmichaelsen/scry"
+Repository = "https://github.com/prmichaelsen/scry"
+Issues = "https://github.com/prmichaelsen/scry/issues"
+
+[project.scripts]
+scry = "scry.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+scry = ["migrations/*.sql"]

scry_mcp-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scry_mcp-0.2.0/src/scry/__init__.py

@@ -0,0 +1,3 @@
+"""scry — marker-indexed SQL cache MCP server."""
+
+__version__ = "0.2.0"

scry_mcp-0.2.0/src/scry/__main__.py

@@ -0,0 +1,10 @@
+"""`python -m scry` entry — delegates to the CLI dispatcher."""
+from __future__ import annotations
+
+import sys
+
+from scry.cli import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scry_mcp-0.2.0/src/scry/cli.py

@@ -0,0 +1,142 @@
+"""scry CLI dispatcher (installed by the `scry-mcp` distribution).
+
+  scry            run the MCP server (default; what Claude calls)
+  scry init       scaffold an `agent/` tree + driver dirs in CWD
+  scry surface    one-shot batch reindex (no server, no watcher)
+  scry version    print the package version
+  scry --help
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from scry import __version__
+
+
+def _cmd_serve() -> int:
+    from scry.server import run_server
+    run_server()
+    return 0
+
+
+_LOCAL_GITIGNORE = """\
+# scry runtime + cache — fully reconstructable from disk, do not commit.
+data/
+runtime/
+"""
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    target = Path(args.path).resolve()
+    namespace = args.namespace
+    target.mkdir(parents=True, exist_ok=True)
+
+    created: list[str] = []
+    preserved: list[str] = []
+
+    def ensure_dir(p: Path, label: str | None = None) -> None:
+        rel = label or (str(p.relative_to(target)) + "/")
+        if p.exists():
+            preserved.append(rel)
+        else:
+            p.mkdir(parents=True)
+            created.append(rel)
+
+    agent = target / "agent"
+    ensure_dir(agent, "agent/")
+    driver = agent / "drivers" / f"@{namespace}" / "scry"
+    ensure_dir(driver / "data")
+    ensure_dir(driver / "runtime")
+    ensure_dir(driver / "scripts")
+
+    # Local .gitignore inside the driver dir — keeps scry's gitignore
+    # concerns self-contained instead of polluting the project root.
+    local_gi = driver / ".gitignore"
+    if local_gi.exists():
+        preserved.append(str(local_gi.relative_to(target)))
+    else:
+        local_gi.write_text(_LOCAL_GITIGNORE, encoding="utf-8")
+        created.append(str(local_gi.relative_to(target)))
+
+    print(f"Initialized scry in {target}")
+    print(f"  namespace: @{namespace}")
+    if (agent / "commands").is_dir() or (agent / "progress.yaml").is_file():
+        print("  detected: ACP project (agent/ tree preserved)")
+    if created:
+        print("  created:")
+        for c in created:
+            print(f"    + {c}")
+    if preserved:
+        print("  already present:")
+        for p in preserved:
+            print(f"    · {p}")
+    print()
+    print("Optional: add `*.scratch.md` to your project .gitignore to honor")
+    print("the ephemeral-doc convention (filename → ephemeral=1 in cache).")
+    print()
+    print("Add this to your MCP client config:")
+    print(json.dumps({
+        "mcpServers": {
+            "scry": {"command": "scry"}
+        }
+    }, indent=2))
+    return 0
+
+
+def _cmd_surface(args: argparse.Namespace) -> int:
+    from scry.config import get_db, get_project_root
+    from scry.service.migration import run_migrations
+    from scry.service.surface import surface
+
+    root = get_project_root()
+    conn = get_db()
+    try:
+        run_migrations(conn=conn)
+        result = surface(conn, project_root=root, force=args.force)
+    finally:
+        conn.close()
+    print(json.dumps(result, indent=2, default=str))
+    return 0
+
+
+def _cmd_version() -> int:
+    print(__version__)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="scry",
+        description="Marker-indexed SQL cache MCP server (scry-mcp package).",
+    )
+    parser.add_argument("--version", action="version", version=f"scry {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    p_init = sub.add_parser("init", help="Scaffold an agent/ tree in the current project.")
+    p_init.add_argument("path", nargs="?", default=".", help="Project directory (default: cwd).")
+    p_init.add_argument("--namespace", default="local", help="Driver namespace (default: local).")
+
+    p_surface = sub.add_parser("surface", help="One-shot batch reindex of the project tree.")
+    p_surface.add_argument("--force", action="store_true", help="Hard-delete records whose source file is gone.")
+
+    sub.add_parser("serve", help="Run the MCP server (default if no subcommand given).")
+    sub.add_parser("version", help="Print the package version.")
+
+    args = parser.parse_args(argv)
+    if args.command is None or args.command == "serve":
+        return _cmd_serve()
+    if args.command == "init":
+        return _cmd_init(args)
+    if args.command == "surface":
+        return _cmd_surface(args)
+    if args.command == "version":
+        return _cmd_version()
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scry_mcp-0.2.0/src/scry/config.py

@@ -0,0 +1,54 @@
+"""Configuration: project root detection, DB path, connection factory."""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+EXCLUDED_DIRS = frozenset({".git", "node_modules", "__pycache__", ".venv", "dist"})
+DEBOUNCE_MS = 150
+BINARY_SNIFF_BYTES = 512
+
+
+def get_project_root(start: Path | None = None) -> Path:
+    p = (start or Path.cwd()).resolve()
+    while p != p.parent:
+        if (p / "agent").is_dir():
+            return p
+        p = p.parent
+    return (start or Path.cwd()).resolve()
+
+
+def get_namespace(project_root: Path | None = None) -> str:
+    root = project_root or get_project_root()
+    drivers = root / "agent" / "drivers"
+    if drivers.is_dir():
+        for entry in sorted(drivers.iterdir()):
+            if entry.name.startswith("@") and (entry / "scry").is_dir():
+                return entry.name[1:]
+    return "local"
+
+
+def get_driver_dir(project_root: Path | None = None) -> Path:
+    root = project_root or get_project_root()
+    return root / "agent" / "drivers" / f"@{get_namespace(root)}" / "scry"
+
+
+def get_db_path(project_root: Path | None = None) -> Path:
+    return get_driver_dir(project_root) / "data" / "project.db"
+
+
+def get_lock_path(project_root: Path | None = None) -> Path:
+    return get_driver_dir(project_root) / "runtime" / "lock"
+
+
+def get_driver_scripts_dir(project_root: Path | None = None) -> Path:
+    return get_driver_dir(project_root) / "scripts"
+
+
+def get_db(db_path: Path | None = None) -> sqlite3.Connection:
+    path = db_path or get_db_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(path), timeout=10)
+    conn.execute("PRAGMA journal_mode = WAL")
+    conn.row_factory = sqlite3.Row
+    return conn