sylvan 1.0.0__tar.gz

sylvan-1.0.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.3
+Name: sylvan
+Version: 1.0.0
+Summary: Unified code + documentation retrieval MCP server
+Author: darki73
+Author-email: darki73 <apple.zhivolupov@gmail.com>
+Requires-Dist: mcp>=1.10.0,<2.0.0
+Requires-Dist: tree-sitter-language-pack>=0.7.0,<1.0.0
+Requires-Dist: sqlite-vec>=0.1.0,<1.0.0
+Requires-Dist: pathspec>=0.12.0,<1.0.0
+Requires-Dist: pyyaml>=6.0,<7.0
+Requires-Dist: tiktoken>=0.12.0,<1.0.0
+Requires-Dist: fastembed>=0.4.0,<1.0.0
+Requires-Dist: ollama>=0.6.1,<1.0.0
+Requires-Dist: structlog>=25.5.0,<27.0.0
+Requires-Dist: claude-agent-sdk==0.1.48
+Requires-Dist: aiosqlite>=0.21.0,<1.0.0
+Requires-Dist: jinja2>=3.1,<4.0
+Requires-Dist: uvicorn>=0.30.0,<1.0.0
+Requires-Dist: starlette>=0.38.0,<1.0.0
+Requires-Dist: watchfiles>=1.0.0 ; extra == 'all'
+Requires-Dist: asyncpg>=0.30.0 ; extra == 'all'
+Requires-Dist: asyncpg>=0.30.0 ; extra == 'postgres'
+Requires-Dist: watchfiles>=1.0.0 ; extra == 'watch'
+Requires-Python: >=3.12
+Provides-Extra: all
+Provides-Extra: postgres
+Provides-Extra: watch
+Description-Content-Type: text/markdown
+
+# Sylvan
+
+Code intelligence platform for AI agents. Search, analyze, and navigate codebases through MCP tools — returning exactly the code your agent needs at a fraction of the token cost.
+
+## Why
+
+AI agents burn tokens reading entire files when they need one function. They grep across directories to trace a dependency. They piece together call chains one file at a time. Every wasted read costs money and context window space.
+
+Sylvan indexes your codebase into a structured database of symbols, sections, and import relationships, then exposes it through 52 MCP tools. Your agent asks for what it needs and gets exactly that — function signatures, blast radius, dependency graphs, semantic search results. Typical token savings exceed 80%.
+
+## Dashboard
+
+![Overview](docs/overview.png)
+
+<details>
+<summary>More screenshots</summary>
+
+**Search** — find code by name, signature, or keywords with syntax-highlighted source
+![Search](docs/search.png)
+
+**Session** — live token efficiency tracking per session and all-time
+![Session](docs/session.png)
+
+**Quality Report** — code smells, security findings, test/doc coverage
+![Quality](docs/quality.png)
+
+**Blast Radius** — visualize impact before changing a symbol
+![Blast Radius](docs/blast-radius.png)
+
+**Libraries** — indexed third-party packages with symbol counts
+![Libraries](docs/libraries.png)
+
+</details>
+
+## Features
+
+- 52 MCP tools for search, browsing, analysis, and refactoring
+- 34 programming languages via tree-sitter
+- Hybrid search — full-text (FTS5) + vector similarity with ranked fusion
+- Blast radius analysis before any refactor
+- Dependency graphs, call chains, class hierarchies
+- Third-party library indexing (pip, npm, cargo, go)
+- Multi-repo workspaces with cross-repo analysis
+- Code quality reports — smells, security, duplication, dead code
+- Web dashboard with live token efficiency tracking
+- Multi-instance cluster support
+
+## Quick start
+
+```bash
+pip install sylvan
+```
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "sylvan": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/sylvan", "sylvan", "serve"]
+    }
+  }
+}
+```
+
+Your agent handles the rest — index a project, search for code, navigate with precision.
+
+## Documentation
+
+Full docs at [darki73.github.io/sylvan](https://darki73.github.io/sylvan/)
+
+## License
+
+Non-commercial open source. Free to use, modify, and distribute with attribution. See [LICENSE](LICENSE) for details.

sylvan-1.0.0/README.md

@@ -0,0 +1,75 @@
+# Sylvan
+
+Code intelligence platform for AI agents. Search, analyze, and navigate codebases through MCP tools — returning exactly the code your agent needs at a fraction of the token cost.
+
+## Why
+
+AI agents burn tokens reading entire files when they need one function. They grep across directories to trace a dependency. They piece together call chains one file at a time. Every wasted read costs money and context window space.
+
+Sylvan indexes your codebase into a structured database of symbols, sections, and import relationships, then exposes it through 52 MCP tools. Your agent asks for what it needs and gets exactly that — function signatures, blast radius, dependency graphs, semantic search results. Typical token savings exceed 80%.
+
+## Dashboard
+
+![Overview](docs/overview.png)
+
+<details>
+<summary>More screenshots</summary>
+
+**Search** — find code by name, signature, or keywords with syntax-highlighted source
+![Search](docs/search.png)
+
+**Session** — live token efficiency tracking per session and all-time
+![Session](docs/session.png)
+
+**Quality Report** — code smells, security findings, test/doc coverage
+![Quality](docs/quality.png)
+
+**Blast Radius** — visualize impact before changing a symbol
+![Blast Radius](docs/blast-radius.png)
+
+**Libraries** — indexed third-party packages with symbol counts
+![Libraries](docs/libraries.png)
+
+</details>
+
+## Features
+
+- 52 MCP tools for search, browsing, analysis, and refactoring
+- 34 programming languages via tree-sitter
+- Hybrid search — full-text (FTS5) + vector similarity with ranked fusion
+- Blast radius analysis before any refactor
+- Dependency graphs, call chains, class hierarchies
+- Third-party library indexing (pip, npm, cargo, go)
+- Multi-repo workspaces with cross-repo analysis
+- Code quality reports — smells, security, duplication, dead code
+- Web dashboard with live token efficiency tracking
+- Multi-instance cluster support
+
+## Quick start
+
+```bash
+pip install sylvan
+```
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "sylvan": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/sylvan", "sylvan", "serve"]
+    }
+  }
+}
+```
+
+Your agent handles the rest — index a project, search for code, navigate with precision.
+
+## Documentation
+
+Full docs at [darki73.github.io/sylvan](https://darki73.github.io/sylvan/)
+
+## License
+
+Non-commercial open source. Free to use, modify, and distribute with attribution. See [LICENSE](LICENSE) for details.

sylvan-1.0.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "sylvan"
+version = "1.0.0"
+description = "Unified code + documentation retrieval MCP server"
+readme = "README.md"
+authors = [
+    { name = "darki73", email = "apple.zhivolupov@gmail.com" },
+]
+requires-python = ">=3.12"
+dependencies = [
+    "mcp>=1.10.0,<2.0.0",
+    "tree-sitter-language-pack>=0.7.0,<1.0.0",
+    "sqlite-vec>=0.1.0,<1.0.0",
+    "pathspec>=0.12.0,<1.0.0",
+    "pyyaml>=6.0,<7.0",
+    "tiktoken>=0.12.0,<1.0.0",
+    "fastembed>=0.4.0,<1.0.0",
+    "ollama>=0.6.1,<1.0.0",
+    "structlog>=25.5.0,<27.0.0",
+    "claude-agent-sdk==0.1.48",
+    "aiosqlite>=0.21.0,<1.0.0",
+    "jinja2>=3.1,<4.0",
+    "uvicorn>=0.30.0,<1.0.0",
+    "starlette>=0.38.0,<1.0.0",
+]
+
+[project.optional-dependencies]
+watch = ["watchfiles>=1.0.0"]
+postgres = ["asyncpg>=0.30.0"]
+all = ["watchfiles>=1.0.0", "asyncpg>=0.30.0"]
+
+[project.scripts]
+sylvan = "sylvan.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.10.6,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_classes = "Test*"
+python_functions = "test_*"
+asyncio_mode = "auto"
+filterwarnings = [
+    "ignore::pytest.PytestUnraisableExceptionWarning",
+    "ignore::pytest.PytestUnhandledThreadExceptionWarning",
+    "ignore:coroutine 'watch_folder' was never awaited:RuntimeWarning",
+]
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+check_untyped_defs = true
+ignore_missing_imports = true
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0",
+    "pytest-asyncio>=1.3",
+    "pytest-cov>=7.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14",
+    "pre-commit>=4.0",
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.27",
+]

sylvan-1.0.0/src/sylvan/__init__.py

@@ -0,0 +1,8 @@
+"""Sylvan — Unified code + documentation retrieval MCP server."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("sylvan")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"

sylvan-1.0.0/src/sylvan/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m sylvan`."""
+
+from sylvan.cli import main
+
+if __name__ == "__main__":
+    main()

sylvan-1.0.0/src/sylvan/analysis/impact/blast_radius.py

@@ -0,0 +1,135 @@
+"""Blast radius analysis -- estimate impact of changing a symbol."""
+
+import re
+from collections import deque
+
+from sylvan.database.orm import Symbol
+from sylvan.database.orm.models.blob import Blob
+from sylvan.database.orm.runtime.connection_manager import get_backend
+
+
+async def get_blast_radius(
+    symbol_id: str,
+    max_depth: int = 3,
+) -> dict:
+    """Estimate the blast radius of changing a symbol.
+
+    Uses BFS through the reference graph + text confirmation.
+
+    Args:
+        symbol_id: Unique identifier of the target symbol.
+        max_depth: Maximum BFS traversal depth.
+
+    Returns:
+        Dictionary with "symbol", "confirmed", "potential",
+        "depth_reached", and "total_affected" keys. Returns an error
+        dict if the symbol is not found.
+    """
+    backend = get_backend()
+
+    target = await (
+        Symbol.query()
+        .select("symbols.*", "f.path as file_path", "f.content_hash", "f.repo_id")
+        .join("files f", "f.id = symbols.file_id")
+        .where("symbols.symbol_id", symbol_id)
+        .first()
+    )
+
+    if target is None:
+        return {"error": "symbol_not_found", "symbol_id": symbol_id}
+
+    target_name = target.name
+    target_file_id = target.file_id
+    target_file_path = getattr(target, "file_path", "")
+    repo_id = getattr(target, "repo_id", None)
+
+    visited_files: set[int] = {target_file_id}
+    queue: deque[tuple[int, int]] = deque()  # (file_id, depth)
+
+    importers = await backend.fetch_all(
+        """SELECT DISTINCT fi.file_id
+           FROM file_imports fi
+           JOIN files f ON f.id = fi.file_id
+           WHERE f.repo_id = ?
+           AND (fi.resolved_file_id = ?
+                OR fi.specifier LIKE ?)""",
+        [repo_id, target_file_id, f"%{target_file_path.rsplit('/', 1)[-1].rsplit('.', 1)[0]}%"],
+    )
+
+    for imp in importers:
+        fid = imp["file_id"]
+        if fid not in visited_files:
+            queue.append((fid, 1))
+            visited_files.add(fid)
+
+    confirmed = []
+    potential = []
+    depth_reached = 0
+
+    while queue:
+        file_id, depth = queue.popleft()
+        depth_reached = max(depth_reached, depth)
+
+        if depth > max_depth:
+            continue
+
+        file_row = await backend.fetch_one(
+            "SELECT path, content_hash FROM files WHERE id = ?", [file_id]
+        )
+        if file_row is None:
+            continue
+
+        content = await Blob.get(file_row["content_hash"])
+        if content is None:
+            continue
+
+        text = content.decode("utf-8", errors="replace")
+        occurrences = len(re.findall(r'\b' + re.escape(target_name) + r'\b', text))
+
+        entry = {
+            "file": file_row["path"],
+            "depth": depth,
+            "occurrences": occurrences,
+        }
+
+        file_symbols = await (
+            Symbol.where(file_id=file_id)
+            .select("symbol_id", "name", "kind", "line_start")
+            .limit(10)
+            .get()
+        )
+        entry["symbols"] = [
+            {"symbol_id": s.symbol_id, "name": s.name, "kind": s.kind, "line_start": s.line_start}
+            for s in file_symbols
+        ]
+
+        if occurrences > 0:
+            confirmed.append(entry)
+        else:
+            potential.append(entry)
+
+        if depth < max_depth:
+            next_importers = await backend.fetch_all(
+                """SELECT DISTINCT fi.file_id FROM file_imports fi
+                   JOIN files f ON f.id = fi.file_id
+                   WHERE f.repo_id = ? AND fi.resolved_file_id = ?""",
+                [repo_id, file_id],
+            )
+            for ni in next_importers:
+                nfid = ni["file_id"]
+                if nfid not in visited_files:
+                    queue.append((nfid, depth + 1))
+                    visited_files.add(nfid)
+
+    return {
+        "symbol": {
+            "symbol_id": symbol_id,
+            "name": target_name,
+            "kind": target.kind,
+            "file": target_file_path,
+        },
+        "confirmed": confirmed,
+        "potential": potential,
+        "depth_reached": depth_reached,
+        "total_affected": len(confirmed) + len(potential),
+    }

sylvan-1.0.0/src/sylvan/analysis/impact/cross_repo.py

@@ -0,0 +1,223 @@
+"""Cross-repo analysis -- resolve imports and blast radius across repo boundaries."""
+
+import re
+from collections import deque
+
+from sylvan.database.orm.models.blob import Blob
+from sylvan.database.orm.runtime.connection_manager import get_backend
+
+
+async def resolve_cross_repo_imports(
+    repo_ids: list[int],
+) -> int:
+    """Resolve file imports that cross repo boundaries.
+
+    For each unresolved import in any of the given repos, try to match the
+    specifier against files in the other repos. Updates resolved_file_id
+    in the file_imports table.
+
+    Args:
+        repo_ids: List of repository database IDs to scan.
+
+    Returns:
+        Number of cross-repo imports resolved.
+    """
+    backend = get_backend()
+
+    file_lookup: dict[str, int] = {}
+    for row in await backend.fetch_all(
+        f"""SELECT id, path, repo_id FROM files
+           WHERE repo_id IN ({",".join("?" * len(repo_ids))})""",
+        repo_ids,
+    ):
+        fid = row["id"]
+        path = row["path"]
+        file_lookup[path] = fid
+        filename = path.rsplit("/", 1)[-1]
+        file_lookup.setdefault(filename, fid)
+        stem = filename.rsplit(".", 1)[0]
+        file_lookup.setdefault(stem, fid)
+        dotpath = path.replace("/", ".").rsplit(".", 1)[0]
+        file_lookup.setdefault(dotpath, fid)
+
+    unresolved = await backend.fetch_all(
+        f"""SELECT fi.id, fi.specifier, fi.file_id, f.repo_id
+           FROM file_imports fi
+           JOIN files f ON f.id = fi.file_id
+           WHERE f.repo_id IN ({",".join("?" * len(repo_ids))})
+           AND fi.resolved_file_id IS NULL""",
+        repo_ids,
+    )
+
+    resolved_count = 0
+    for imp in unresolved:
+        spec = imp["specifier"]
+        source_repo_id = imp["repo_id"]
+
+        candidates = []
+
+        if spec in file_lookup:
+            target_fid = file_lookup[spec]
+            target_repo = await backend.fetch_one(
+                "SELECT repo_id FROM files WHERE id = ?", [target_fid]
+            )
+            if target_repo and target_repo["repo_id"] != source_repo_id:
+                candidates.append(target_fid)
+
+        stem = spec.rsplit("/", 1)[-1].rsplit(".", 1)[0]
+        if stem in file_lookup and not candidates:
+            target_fid = file_lookup[stem]
+            target_repo = await backend.fetch_one(
+                "SELECT repo_id FROM files WHERE id = ?", [target_fid]
+            )
+            if target_repo and target_repo["repo_id"] != source_repo_id:
+                candidates.append(target_fid)
+
+        dotpath = spec.replace(".", "/")
+        for suffix in ("", ".py", ".ts", ".js", ".go"):
+            key = dotpath + suffix
+            if key in file_lookup and not candidates:
+                target_fid = file_lookup[key]
+                target_repo = await backend.fetch_one(
+                    "SELECT repo_id FROM files WHERE id = ?", [target_fid]
+                )
+                if target_repo and target_repo["repo_id"] != source_repo_id:
+                    candidates.append(target_fid)
+
+        if candidates:
+            await backend.execute(
+                "UPDATE file_imports SET resolved_file_id = ? WHERE id = ?",
+                [candidates[0], imp["id"]],
+            )
+            resolved_count += 1
+
+    if resolved_count:
+        await backend.commit()
+    return resolved_count
+
+
+async def cross_repo_blast_radius(
+    symbol_id: str,
+    repo_ids: list[int],
+    max_depth: int = 3,
+) -> dict:
+    """Blast radius analysis that crosses repo boundaries.
+
+    Like get_blast_radius but follows imports across all repos in the workspace.
+
+    Args:
+        symbol_id: Unique identifier of the target symbol.
+        repo_ids: List of repository database IDs to scan.
+        max_depth: Maximum BFS traversal depth.
+
+    Returns:
+        Dictionary with "symbol", "confirmed", "potential",
+        "depth_reached", "total_affected", "cross_repo_affected",
+        and "repos_scanned" keys. Returns an error dict if the
+        symbol is not found.
+    """
+    backend = get_backend()
+
+    target = await backend.fetch_one(
+        """SELECT s.*, f.path as file_path, f.repo_id, f.content_hash,
+                  r.name as repo_name
+           FROM symbols s
+           JOIN files f ON f.id = s.file_id
+           JOIN repos r ON r.id = f.repo_id
+           WHERE s.symbol_id = ?""",
+        [symbol_id],
+    )
+
+    if target is None:
+        return {"error": "symbol_not_found", "symbol_id": symbol_id}
+
+    target_dict = dict(target)
+    target_name = target_dict["name"]
+    target_file_id = target_dict["file_id"]
+
+    visited_files: set[int] = {target_file_id}
+    queue: deque[tuple[int, int]] = deque()
+
+    repo_filter = ",".join("?" * len(repo_ids))
+    importers = await backend.fetch_all(
+        f"""SELECT DISTINCT fi.file_id
+           FROM file_imports fi
+           JOIN files f ON f.id = fi.file_id
+           WHERE f.repo_id IN ({repo_filter})
+           AND (fi.resolved_file_id = ? OR fi.specifier LIKE ?)""",
+        [*repo_ids, target_file_id, f"%{target_dict['file_path'].rsplit('/', 1)[-1].rsplit('.', 1)[0]}%"],
+    )
+
+    for imp in importers:
+        fid = imp["file_id"]
+        if fid not in visited_files:
+            queue.append((fid, 1))
+            visited_files.add(fid)
+
+    confirmed = []
+    potential = []
+    depth_reached = 0
+
+    while queue:
+        file_id, depth = queue.popleft()
+        depth_reached = max(depth_reached, depth)
+        if depth > max_depth:
+            continue
+
+        file_row = await backend.fetch_one(
+            """SELECT f.path, f.content_hash, r.name as repo_name
+               FROM files f JOIN repos r ON r.id = f.repo_id
+               WHERE f.id = ?""",
+            [file_id],
+        )
+        if file_row is None:
+            continue
+
+        content = await Blob.get(file_row["content_hash"])
+        if content is None:
+            continue
+
+        text = content.decode("utf-8", errors="replace")
+        occurrences = len(re.findall(r"\b" + re.escape(target_name) + r"\b", text))
+
+        entry = {
+            "file": file_row["path"],
+            "repo": file_row["repo_name"],
+            "depth": depth,
+            "occurrences": occurrences,
+            "cross_repo": file_row["repo_name"] != target_dict["repo_name"],
+        }
+
+        if occurrences > 0:
+            confirmed.append(entry)
+        else:
+            potential.append(entry)
+
+        if depth < max_depth:
+            next_importers = await backend.fetch_all(
+                f"""SELECT DISTINCT fi2.file_id FROM file_imports fi2
+                   JOIN files f2 ON f2.id = fi2.file_id
+                   WHERE f2.repo_id IN ({repo_filter})
+                   AND fi2.resolved_file_id = ?""",
+                [*repo_ids, file_id],
+            )
+            for ni in next_importers:
+                if ni["file_id"] not in visited_files:
+                    queue.append((ni["file_id"], depth + 1))
+                    visited_files.add(ni["file_id"])
+
+    return {
+        "symbol": {
+            "symbol_id": target_dict["symbol_id"],
+            "name": target_name,
+            "kind": target_dict["kind"],
+            "file": target_dict["file_path"],
+            "repo": target_dict["repo_name"],
+        },
+        "confirmed": confirmed,
+        "potential": potential,
+        "depth_reached": depth_reached,
+        "total_affected": len(confirmed) + len(potential),
+        "cross_repo_affected": sum(1 for c in confirmed + potential if c.get("cross_repo")),
+        "repos_scanned": len(repo_ids),
+    }