symdex 0.1.0__tar.gz

symdex-0.1.0/LICENSE

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

symdex-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: symdex
+Version: 0.1.0
+Summary: Universal code-indexer MCP server for AI coding agents
+Author: Muhammad Husnain
+License: MIT
+Project-URL: Homepage, https://symdex.dev
+Project-URL: Repository, https://github.com/husnain/symdex
+Keywords: mcp,code-indexer,ai,llm,tree-sitter,semantic-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tree-sitter<0.26,>=0.25
+Requires-Dist: tree-sitter-python>=0.1
+Requires-Dist: tree-sitter-javascript>=0.1
+Requires-Dist: tree-sitter-typescript>=0.1
+Requires-Dist: tree-sitter-go>=0.1
+Requires-Dist: tree-sitter-rust>=0.1
+Requires-Dist: tree-sitter-java>=0.1
+Requires-Dist: tree-sitter-php>=0.1
+Requires-Dist: tree-sitter-c-sharp>=0.1
+Requires-Dist: tree-sitter-c>=0.1
+Requires-Dist: tree-sitter-cpp>=0.1
+Requires-Dist: tree-sitter-elixir>=0.1
+Requires-Dist: tree-sitter-ruby>=0.1
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: sentence-transformers>=3.0
+Requires-Dist: sqlite-vec>=0.1
+Requires-Dist: numpy>=1.26
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: pytest-bdd>=7; extra == "dev"
+Dynamic: license-file
+
+# SymDex
+
+Universal code-indexer MCP server for AI coding agents — Claude, Codex, Gemini, Cursor, and any agent that speaks MCP.
+
+**The problem:** Reading a full file to find one function costs ~7,500 tokens. SymDex pre-indexes your codebase once, then returns precise byte-offset locations. The same lookup costs ~200 tokens — a **97% reduction**.
+
+## Installation
+
+```bash
+pip install symdex
+```
+
+## Quickstart
+
+### 1. Index a project
+
+```bash
+symdex index ./myproject --name myproject
+```
+
+### 2. Search for a symbol
+
+```bash
+symdex search "validate email"
+```
+
+### 3. Start the MCP server
+
+```bash
+symdex serve          # stdio mode (for local agents)
+symdex serve --port 8080  # HTTP mode
+```
+
+## MCP Tool Reference
+
+| Tool | Description |
+|------|-------------|
+| `index_folder` | Index a local folder (run once per session) |
+| `search_symbols` | Find function/class by name (~200 tokens) |
+| `get_symbol` | Get one function's full source by byte offset |
+| `get_file_outline` | All symbols in a file, no full content |
+| `get_repo_outline` | Directory structure + symbol stats |
+| `search_text` | Text search, returns matching lines only |
+| `get_file_tree` | Directory tree without content |
+| `list_repos` | List all indexed repos |
+| `get_symbols` | Bulk symbol retrieval |
+| `index_repo` | Index a named repo |
+| `invalidate_cache` | Force re-index on next request |
+| `semantic_search` | Find symbols by meaning (embedding similarity) |
+| `get_callers` | Who calls this function |
+| `get_callees` | What this function calls |
+
+## CLI Commands
+
+```bash
+symdex index ./myproject              # Index a folder
+symdex search "validate email"        # Search symbols
+symdex find MyClass                   # Exact name lookup
+symdex outline myproject/module.py --repo myproject   # File outline
+symdex text "TODO" --repo myproject   # Text search
+symdex semantic "parse authentication token" --repo myproject  # Semantic search
+symdex callers my_function --repo myproject   # Call graph: who calls this
+symdex callees my_function --repo myproject   # Call graph: what this calls
+symdex repos                          # List indexed repos
+symdex serve                          # Start MCP server
+```
+
+## Supported Languages
+
+Python, JavaScript, TypeScript, Go, Rust, Java, PHP, C#, C, C++, Elixir, Ruby (13 languages via tree-sitter)
+
+## Agent Configuration
+
+Add to your agent's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "symdex": {
+      "command": "symdex",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE)

symdex-0.1.0/README.md

@@ -0,0 +1,89 @@
+# SymDex
+
+Universal code-indexer MCP server for AI coding agents — Claude, Codex, Gemini, Cursor, and any agent that speaks MCP.
+
+**The problem:** Reading a full file to find one function costs ~7,500 tokens. SymDex pre-indexes your codebase once, then returns precise byte-offset locations. The same lookup costs ~200 tokens — a **97% reduction**.
+
+## Installation
+
+```bash
+pip install symdex
+```
+
+## Quickstart
+
+### 1. Index a project
+
+```bash
+symdex index ./myproject --name myproject
+```
+
+### 2. Search for a symbol
+
+```bash
+symdex search "validate email"
+```
+
+### 3. Start the MCP server
+
+```bash
+symdex serve          # stdio mode (for local agents)
+symdex serve --port 8080  # HTTP mode
+```
+
+## MCP Tool Reference
+
+| Tool | Description |
+|------|-------------|
+| `index_folder` | Index a local folder (run once per session) |
+| `search_symbols` | Find function/class by name (~200 tokens) |
+| `get_symbol` | Get one function's full source by byte offset |
+| `get_file_outline` | All symbols in a file, no full content |
+| `get_repo_outline` | Directory structure + symbol stats |
+| `search_text` | Text search, returns matching lines only |
+| `get_file_tree` | Directory tree without content |
+| `list_repos` | List all indexed repos |
+| `get_symbols` | Bulk symbol retrieval |
+| `index_repo` | Index a named repo |
+| `invalidate_cache` | Force re-index on next request |
+| `semantic_search` | Find symbols by meaning (embedding similarity) |
+| `get_callers` | Who calls this function |
+| `get_callees` | What this function calls |
+
+## CLI Commands
+
+```bash
+symdex index ./myproject              # Index a folder
+symdex search "validate email"        # Search symbols
+symdex find MyClass                   # Exact name lookup
+symdex outline myproject/module.py --repo myproject   # File outline
+symdex text "TODO" --repo myproject   # Text search
+symdex semantic "parse authentication token" --repo myproject  # Semantic search
+symdex callers my_function --repo myproject   # Call graph: who calls this
+symdex callees my_function --repo myproject   # Call graph: what this calls
+symdex repos                          # List indexed repos
+symdex serve                          # Start MCP server
+```
+
+## Supported Languages
+
+Python, JavaScript, TypeScript, Go, Rust, Java, PHP, C#, C, C++, Elixir, Ruby (13 languages via tree-sitter)
+
+## Agent Configuration
+
+Add to your agent's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "symdex": {
+      "command": "symdex",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE)

symdex-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "symdex"
+version = "0.1.0"
+description = "Universal code-indexer MCP server for AI coding agents"
+authors = [{name = "Muhammad Husnain"}]
+license = {text = "MIT"}
+requires-python = ">=3.11"
+readme = "README.md"
+keywords = ["mcp", "code-indexer", "ai", "llm", "tree-sitter", "semantic-search"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "tree-sitter>=0.25,<0.26",
+    "tree-sitter-python>=0.1",
+    "tree-sitter-javascript>=0.1",
+    "tree-sitter-typescript>=0.1",
+    "tree-sitter-go>=0.1",
+    "tree-sitter-rust>=0.1",
+    "tree-sitter-java>=0.1",
+    "tree-sitter-php>=0.1",
+    # tree-sitter-dart: not available on PyPI, excluded
+    "tree-sitter-c-sharp>=0.1",
+    "tree-sitter-c>=0.1",
+    "tree-sitter-cpp>=0.1",
+    "tree-sitter-elixir>=0.1",
+    "tree-sitter-ruby>=0.1",
+    "fastmcp>=2.0",
+    "typer>=0.12",
+    "rich>=13",
+    "sentence-transformers>=3.0",
+    "sqlite-vec>=0.1",
+    "numpy>=1.26",
+]
+
+[project.urls]
+Homepage = "https://symdex.dev"
+Repository = "https://github.com/husnain/symdex"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-cov>=4",
+    "pytest-bdd>=7",
+]
+
+[project.scripts]
+symdex = "symdex.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["symdex*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py", "*_steps.py"]

symdex-0.1.0/setup.cfg

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

symdex-0.1.0/symdex/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) 2026 Muhammad Husnain
+# This file is part of SymDex.
+# License: See LICENSE file in the project root.

symdex-0.1.0/symdex/cli.py

@@ -0,0 +1,314 @@
+# Copyright (c) 2026 Muhammad Husnain
+# This file is part of SymDex.
+# License: See LICENSE file in the project root.
+
+import json
+import os
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from symdex.core.indexer import index_folder as _index_folder, invalidate as _invalidate
+from symdex.core.storage import (
+    get_connection,
+    get_db_path,
+    get_registry_path,  # noqa: F401 — imported for monkeypatching
+    query_file_symbols,
+    query_repos,
+    search_text_in_index,
+    upsert_repo,
+)
+from symdex.search.symbol_search import search_symbols as _search_symbols
+
+app = typer.Typer(name="symdex", help="SymDex — universal code indexer")
+console = Console()
+err_console = Console(stderr=True)
+
+
+@app.command()
+def index(
+    path: str = typer.Argument(..., help="Directory to index"),
+    name: str = typer.Option(None, "--name", "-n", help="Repo name (defaults to folder name)"),
+) -> None:
+    """Index a folder and register it."""
+    if not os.path.isdir(path):
+        err_console.print(f"[red]Error:[/red] Path does not exist: {path}")
+        raise typer.Exit(code=1)
+    result = _index_folder(path, name=name)
+    upsert_repo(result.repo, root_path=os.path.abspath(path), db_path=result.db_path)
+    table = Table(title="Index Result")
+    table.add_column("Repo", style="cyan")
+    table.add_column("Indexed", style="green")
+    table.add_column("Skipped", style="yellow")
+    table.add_column("DB Path")
+    table.add_row(result.repo, str(result.indexed_count), str(result.skipped_count), result.db_path)
+    console.print(table)
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Symbol name to search for"),
+    repo: str = typer.Option(None, "--repo", "-r", help="Repo name (omit to search all repos)"),
+    kind: str = typer.Option(None, "--kind", "-k", help="Symbol kind filter"),
+    limit: int = typer.Option(20, "--limit", "-l", help="Max results"),
+    json_output: bool = typer.Option(False, "--json", help="Output raw JSON"),
+) -> None:
+    """Find functions/classes by name (omit --repo to search all indexed repos)."""
+    if repo:
+        conn = get_connection(get_db_path(repo))
+        try:
+            symbols = _search_symbols(conn, repo=repo, query=query, kind=kind, limit=limit)
+        finally:
+            conn.close()
+    else:
+        from symdex.graph.registry import search_across_repos
+        symbols = search_across_repos(query=query, kind=kind, limit=limit)
+    if not symbols:
+        err_console.print(f"[red]Error:[/red] No symbols found matching: {query}")
+        raise typer.Exit(code=1)
+    if json_output:
+        typer.echo(json.dumps({"symbols": symbols}))
+        return
+    table = Table(title=f"Symbols matching '{query}'")
+    table.add_column("Repo", style="blue")
+    table.add_column("Name", style="cyan")
+    table.add_column("Kind", style="magenta")
+    table.add_column("File")
+    table.add_column("Start", style="dim")
+    for s in symbols:
+        table.add_row(s.get("repo", repo or ""), s["name"], s["kind"], s["file"], str(s["start_byte"]))
+    console.print(table)
+
+
+@app.command()
+def find(
+    name: str = typer.Argument(..., help="Exact symbol name"),
+    repo: str = typer.Option(None, "--repo", "-r", help="Repo name"),
+    json_output: bool = typer.Option(False, "--json", help="Output raw JSON"),
+) -> None:
+    """Exact symbol name lookup by symbol name."""
+    if not repo:
+        err_console.print("[red]Error:[/red] --repo is required")
+        raise typer.Exit(code=1)
+    conn = get_connection(get_db_path(repo))
+    try:
+        symbols = _search_symbols(conn, repo=repo, query=name, limit=1)
+    finally:
+        conn.close()
+    if not symbols:
+        err_console.print(f"[red]Error:[/red] Symbol not found: {name}")
+        raise typer.Exit(code=1)
+    if json_output:
+        typer.echo(json.dumps({"symbols": symbols}))
+        return
+    s = symbols[0]
+    table = Table(title=f"Symbol: {name}")
+    table.add_column("Field")
+    table.add_column("Value")
+    for k, v in s.items():
+        table.add_row(k, str(v) if v is not None else "")
+    console.print(table)
+
+
+@app.command()
+def outline(
+    file: str = typer.Argument(..., help="Relative file path within repo"),
+    repo: str = typer.Option(..., "--repo", "-r", help="Repo name"),
+    json_output: bool = typer.Option(False, "--json", help="Output raw JSON"),
+) -> None:
+    """List all symbols in a file."""
+    conn = get_connection(get_db_path(repo))
+    try:
+        symbols = query_file_symbols(conn, repo=repo, file=file)
+    finally:
+        conn.close()
+    if not symbols:
+        err_console.print(f"[red]Error:[/red] No symbols found in: {file}")
+        raise typer.Exit(code=1)
+    if json_output:
+        typer.echo(json.dumps({"symbols": symbols}))
+        return
+    table = Table(title=f"Outline: {file}")
+    table.add_column("Name", style="cyan")
+    table.add_column("Kind", style="magenta")
+    table.add_column("Start", style="dim")
+    table.add_column("End", style="dim")
+    for s in symbols:
+        table.add_row(s["name"], s["kind"], str(s["start_byte"]), str(s["end_byte"]))
+    console.print(table)
+
+
+@app.command()
+def text(
+    query: str = typer.Argument(..., help="Text to search for"),
+    repo: str = typer.Option(None, "--repo", "-r", help="Repo name"),
+    pattern: str = typer.Option(None, "--pattern", "-p", help="File glob pattern"),
+    json_output: bool = typer.Option(False, "--json", help="Output raw JSON"),
+) -> None:
+    """Text search across indexed files."""
+    if not repo:
+        err_console.print("[red]Error:[/red] --repo is required")
+        raise typer.Exit(code=1)
+    all_repos = query_repos()
+    repo_info = next((r for r in all_repos if r["name"] == repo), None)
+    if repo_info is None:
+        err_console.print(f"[red]Error:[/red] Repo not indexed: {repo}")
+        raise typer.Exit(code=1)
+    conn = get_connection(get_db_path(repo))
+    try:
+        matches = search_text_in_index(conn, repo=repo, query=query, repo_root=repo_info["root_path"], file_pattern=pattern)
+    finally:
+        conn.close()
+    if not matches:
+        err_console.print(f"[red]Error:[/red] No matches found for: {query}")
+        raise typer.Exit(code=1)
+    if json_output:
+        typer.echo(json.dumps({"matches": matches}))
+        return
+    table = Table(title=f"Text matches for '{query}'")
+    table.add_column("File")
+    table.add_column("Line", style="dim")
+    table.add_column("Text")
+    for m in matches:
+        table.add_row(m["file"], str(m["line"]), m["text"])
+    console.print(table)
+
+
+@app.command()
+def semantic(
+    query: str = typer.Argument(..., help="Natural language query"),
+    repo: str = typer.Option(None, "--repo", "-r", help="Repo name"),
+    limit: int = typer.Option(10, "--limit", "-l", help="Max results"),
+    json_output: bool = typer.Option(False, "--json", help="Output raw JSON"),
+) -> None:
+    """Semantic similarity search by meaning."""
+    from symdex.search.semantic import search_semantic
+    if not repo:
+        err_console.print("[red]Error:[/red] --repo is required")
+        raise typer.Exit(code=1)
+    conn = get_connection(get_db_path(repo))
+    try:
+        results = search_semantic(conn, query=query, repo=repo, limit=limit)
+    finally:
+        conn.close()
+    if not results:
+        err_console.print(f"[red]Error:[/red] No semantic matches found for: {query}")
+        raise typer.Exit(code=1)
+    if json_output:
+        typer.echo(json.dumps({"symbols": results}))
+        return
+    table = Table(title=f"Semantic matches for '{query}'")
+    table.add_column("Name", style="cyan")
+    table.add_column("Kind", style="magenta")
+    table.add_column("Score", style="green")
+    table.add_column("File")
+    for s in results:
+        table.add_row(s["name"], s["kind"], str(s["score"]), s["file"])
+    console.print(table)
+
+
+@app.command()
+def callers(
+    name: str = typer.Argument(..., help="Function name to find callers of"),
+    repo: str = typer.Option(..., "--repo", "-r", help="Repo name"),
+    json_output: bool = typer.Option(False, "--json", help="Output raw JSON"),
+) -> None:
+    """Show all functions that call the named function."""
+    from symdex.graph.call_graph import get_callers as _get_callers
+    conn = get_connection(get_db_path(repo))
+    try:
+        results = _get_callers(conn, name=name, repo=repo)
+    finally:
+        conn.close()
+    if not results:
+        err_console.print(f"[red]Error:[/red] No callers found for: {name}")
+        raise typer.Exit(code=1)
+    if json_output:
+        typer.echo(json.dumps({"callers": results}))
+        return
+    table = Table(title=f"Callers of '{name}'")
+    table.add_column("Name", style="cyan")
+    table.add_column("Kind", style="magenta")
+    table.add_column("File")
+    for s in results:
+        table.add_row(s["name"], s["kind"], s["file"])
+    console.print(table)
+
+
+@app.command()
+def callees(
+    name: str = typer.Argument(..., help="Function name to find callees of"),
+    repo: str = typer.Option(..., "--repo", "-r", help="Repo name"),
+    json_output: bool = typer.Option(False, "--json", help="Output raw JSON"),
+) -> None:
+    """Show all functions called by the named function."""
+    from symdex.graph.call_graph import get_callees as _get_callees
+    conn = get_connection(get_db_path(repo))
+    try:
+        results = _get_callees(conn, name=name, repo=repo)
+    finally:
+        conn.close()
+    if not results:
+        err_console.print(f"[red]Error:[/red] No callees found for: {name}")
+        raise typer.Exit(code=1)
+    if json_output:
+        typer.echo(json.dumps({"callees": results}))
+        return
+    table = Table(title=f"Callees of '{name}'")
+    table.add_column("Name", style="cyan")
+    table.add_column("File")
+    for s in results:
+        table.add_row(s["name"], s.get("file") or "")
+    console.print(table)
+
+
+@app.command()
+def repos(
+    json_output: bool = typer.Option(False, "--json", help="Output raw JSON"),
+) -> None:
+    """List all indexed repositories."""
+    all_repos = query_repos()
+    if not all_repos:
+        err_console.print("[red]Error:[/red] No repos indexed yet.")
+        raise typer.Exit(code=1)
+    if json_output:
+        typer.echo(json.dumps({"repos": all_repos}))
+        return
+    table = Table(title="Indexed Repositories")
+    table.add_column("Name", style="cyan")
+    table.add_column("Root Path")
+    table.add_column("Last Indexed", style="dim")
+    for r in all_repos:
+        table.add_row(r["name"], r["root_path"], str(r.get("last_indexed", "")))
+    console.print(table)
+
+
+@app.command()
+def invalidate(
+    repo: str = typer.Option(..., "--repo", "-r", help="Repo name"),
+    file: str = typer.Option(None, "--file", "-f", help="Specific file to invalidate"),
+    json_output: bool = typer.Option(False, "--json", help="Output raw JSON"),
+) -> None:
+    """Force re-index of a repo or specific file."""
+    count = _invalidate(repo, file=file)
+    if json_output:
+        typer.echo(json.dumps({"invalidated": count}))
+        return
+    console.print(f"Invalidated [green]{count}[/green] record(s) for repo '[cyan]{repo}[/cyan]'")
+
+
+@app.command()
+def serve(
+    port: int = typer.Option(None, "--port", "-p", help="HTTP port (omit for stdio mode)"),
+) -> None:
+    """Start the MCP server."""
+    from symdex.mcp.server import mcp
+    if port:
+        mcp.run(transport="streamable-http", port=port)
+    else:
+        mcp.run()
+
+
+if __name__ == "__main__":
+    app()

symdex-0.1.0/symdex/core/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) 2026 Muhammad Husnain
+# This file is part of SymDex.
+# License: See LICENSE file in the project root.