trelix-mcp 0.5.0__tar.gz

trelix_mcp-0.5.0/.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+*.egg
+build/
+.eggs/
+pip-wheel-metadata/
+
+# dist/ — ignore generated packaging artefacts; binaries are attached via GitHub Releases.
+dist/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Trelix index data — never commit these
+.trelix/
+
+# Test / coverage artefacts
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Ruff / Mypy caches
+.ruff_cache/
+.mypy_cache/
+
+# Environment files — secrets must not be committed
+.env
+.env.local
+.env.*.local
+
+# Claude Code internal data
+.claude/
+
+# uv lockfile (not committed — project uses pip/hatchling)
+uv.lock
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+Thumbs.db
+
+# Distribution / packaging
+*.tar.gz
+*.whl
+MANIFEST
+.superpowers/

trelix_mcp-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Trelix Contributors
+
+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.

trelix_mcp-0.5.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: trelix-mcp
+Version: 0.5.0
+Summary: MCP server for trelix — semantic code search for Claude Code, Cursor, Windsurf, Continue.dev
+Project-URL: Homepage, https://github.com/sairam0424/trelix
+Author: Trelix Contributors
+License: MIT License
+        
+        Copyright (c) 2025 Trelix Contributors
+        
+        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.
+License-File: LICENSE
+Keywords: ai-agent,claude-code,code-intelligence,code-search,cursor,llm,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: trelix>=0.4.0
+Description-Content-Type: text/markdown
+
+# trelix-mcp
+
+MCP server for [trelix](https://github.com/sairam0424/trelix) — semantic code search for Claude Code, Cursor, Windsurf, and Continue.dev.
+
+## Install
+
+```bash
+pip install trelix-mcp
+```
+
+## Usage
+
+### Claude Code
+
+```bash
+claude mcp add trelix -- trelix-mcp
+```
+
+### Cursor (`~/.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "trelix": {
+      "command": "trelix-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### Continue.dev (`.continue/config.json`)
+
+```json
+{
+  "mcpServers": [
+    {
+      "name": "trelix",
+      "command": "trelix-mcp",
+      "args": []
+    }
+  ]
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_code` | Semantic hybrid search over an indexed codebase |
+| `index_codebase` | Index a repository so it can be searched |
+| `get_symbol` | Look up a symbol by qualified name |
+| `blast_radius` | Find all files that depend on a symbol |

trelix_mcp-0.5.0/README.md

@@ -0,0 +1,53 @@
+# trelix-mcp
+
+MCP server for [trelix](https://github.com/sairam0424/trelix) — semantic code search for Claude Code, Cursor, Windsurf, and Continue.dev.
+
+## Install
+
+```bash
+pip install trelix-mcp
+```
+
+## Usage
+
+### Claude Code
+
+```bash
+claude mcp add trelix -- trelix-mcp
+```
+
+### Cursor (`~/.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "trelix": {
+      "command": "trelix-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### Continue.dev (`.continue/config.json`)
+
+```json
+{
+  "mcpServers": [
+    {
+      "name": "trelix",
+      "command": "trelix-mcp",
+      "args": []
+    }
+  ]
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_code` | Semantic hybrid search over an indexed codebase |
+| `index_codebase` | Index a repository so it can be searched |
+| `get_symbol` | Look up a symbol by qualified name |
+| `blast_radius` | Find all files that depend on a symbol |

trelix_mcp-0.5.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/trelix_mcp"]
+
+[project]
+name = "trelix-mcp"
+version = "0.5.0"
+description = "MCP server for trelix — semantic code search for Claude Code, Cursor, Windsurf, Continue.dev"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Trelix Contributors" }]
+requires-python = ">=3.11"
+keywords = ["mcp", "model-context-protocol", "code-search", "claude-code", "cursor", "code-intelligence", "llm", "ai-agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["trelix>=0.4.0", "mcp>=1.0.0", "fastmcp>=2.0.0"]
+
+[project.scripts]
+trelix-mcp = "trelix_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/sairam0424/trelix"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

trelix_mcp-0.5.0/src/trelix_mcp/__init__.py

@@ -0,0 +1,4 @@
+"""trelix MCP server — expose trelix code intelligence as MCP tools."""
+
+__version__ = "0.5.0"
+__all__ = ["__version__"]

trelix_mcp-0.5.0/src/trelix_mcp/server.py

@@ -0,0 +1,175 @@
+import logging
+import sys
+
+logging.basicConfig(
+    stream=sys.stderr,
+    level=logging.INFO,
+    format="[trelix-mcp] %(levelname)s %(message)s",
+)
+
+import signal  # noqa: E402
+from typing import Any, Literal  # noqa: E402
+
+from fastmcp import FastMCP  # noqa: E402
+
+from trelix.core.config import EmbedderConfig, IndexConfig  # noqa: E402
+from trelix.indexing.indexer import Indexer  # noqa: E402
+from trelix.retrieval.retriever import Retriever  # noqa: E402
+from trelix.store.db import Database  # noqa: E402
+
+mcp = FastMCP("trelix")
+_log = logging.getLogger("trelix_mcp")
+
+
+@mcp.tool()
+def search_code(query: str, repo_path: str, k: int = 10) -> list[dict[str, Any]]:
+    """Search a codebase for symbols semantically relevant to *query*.
+
+    Args:
+        query: Natural-language or keyword search query.
+        repo_path: Absolute path to the repository root (must already be indexed).
+        k: Maximum number of results to return (default 10).
+
+    Returns:
+        List of result dicts with keys: file, symbol, kind, lines, score, source,
+        body, language.
+    """
+    _log.info("search_code query=%r repo_path=%r k=%d", query, repo_path, k)
+    config = IndexConfig(repo_path=repo_path)
+    retriever = Retriever(config)
+    context = retriever.retrieve(query)
+    results = context.results[:k]
+    return [
+        {
+            "file": r.file.rel_path,
+            "symbol": r.symbol.qualified_name,
+            "kind": r.symbol.kind,
+            "lines": [r.symbol.line_start, r.symbol.line_end],
+            "score": round(r.score, 4),
+            "source": r.source,
+            "body": r.symbol.body,
+            "language": r.file.language,
+        }
+        for r in results
+    ]
+
+
+@mcp.tool()
+def index_codebase(
+    repo_path: str,
+    provider: Literal["local", "openai", "azure", "voyage", "local-code"] = "local",
+) -> dict[str, Any]:
+    """Index a codebase so it can be searched with search_code.
+
+    Args:
+        repo_path: Absolute path to the repository root.
+        provider: Embedding provider — "local" requires no API key.
+
+    Returns:
+        Indexing statistics dict with keys: files_found, files_indexed,
+        files_skipped, symbols_extracted, chunks_total, chunks_embedded,
+        errors, elapsed_seconds.
+    """
+    _log.info("index_codebase repo_path=%r provider=%r", repo_path, provider)
+    embedder_config = EmbedderConfig(provider=provider)  # type: ignore[call-arg]
+    config = IndexConfig(repo_path=repo_path, embedder=embedder_config)
+    stats = Indexer(config, quiet=True).index()
+    return stats
+
+
+@mcp.tool()
+def get_symbol(qualified_name: str, repo_path: str) -> dict[str, Any] | None:
+    """Look up a symbol by its fully-qualified name.
+
+    Args:
+        qualified_name: e.g. "MyClass.my_method" or "my_function".
+        repo_path: Absolute path to the repository root.
+
+    Returns:
+        Symbol dict or None if not found.  Keys: name, qualified_name, kind,
+        file, line_start, line_end, signature, docstring, body, language.
+    """
+    _log.info("get_symbol qualified_name=%r repo_path=%r", qualified_name, repo_path)
+    config = IndexConfig(repo_path=repo_path)
+    db = Database(config.db_path_absolute)
+    rows = db.get_symbol_by_name(qualified_name)
+    if not rows:
+        # Fall back to bare name lookup
+        name_only = qualified_name.split(".")[-1]
+        rows = db.get_symbol_by_name(name_only)
+        # Filter to exact qualified_name match when possible
+        exact = [s for s in rows if s.qualified_name == qualified_name]
+        if exact:
+            rows = exact
+
+    if not rows:
+        return None
+
+    sym = rows[0]
+    sym_file = db.get_symbol_with_file(sym.id)  # type: ignore[arg-type]
+    if sym_file is None:
+        return None
+    symbol, file = sym_file
+    return {
+        "name": symbol.name,
+        "qualified_name": symbol.qualified_name,
+        "kind": symbol.kind,
+        "file": file.rel_path,
+        "line_start": symbol.line_start,
+        "line_end": symbol.line_end,
+        "signature": symbol.signature,
+        "docstring": symbol.docstring,
+        "body": symbol.body,
+        "language": file.language,
+    }
+
+
+@mcp.tool()
+def blast_radius(symbol_name: str, repo_path: str) -> list[dict[str, Any]]:
+    """Find all symbols that depend on (call or import) a given symbol.
+
+    Useful for impact analysis: "if I change X, what else might break?"
+
+    Args:
+        symbol_name: Name or qualified name of the symbol to analyse.
+        repo_path: Absolute path to the repository root.
+
+    Returns:
+        Deduplicated list of dependent-symbol dicts with keys: file, symbol,
+        kind, line_start, language.
+    """
+    _log.info("blast_radius symbol_name=%r repo_path=%r", symbol_name, repo_path)
+    query = f"blast radius dependencies of {symbol_name}"
+    config = IndexConfig(repo_path=repo_path)
+    retriever = Retriever(config)
+    context = retriever.retrieve(query)
+
+    seen_files: set[str] = set()
+    output: list[dict[str, Any]] = []
+    for r in context.results:
+        file_key = r.file.rel_path
+        if file_key in seen_files:
+            continue
+        seen_files.add(file_key)
+        output.append(
+            {
+                "file": r.file.rel_path,
+                "symbol": r.symbol.qualified_name,
+                "kind": r.symbol.kind,
+                "line_start": r.symbol.line_start,
+                "language": r.file.language,
+            }
+        )
+    return output
+
+
+def main() -> None:
+    """Entry point for the trelix-mcp server (stdio transport)."""
+
+    def _handle_sigterm(signum: int, frame: Any) -> None:
+        _log.info("Received SIGTERM — shutting down")
+        sys.exit(0)
+
+    signal.signal(signal.SIGTERM, _handle_sigterm)
+    _log.info("trelix-mcp starting (transport=stdio)")
+    mcp.run(transport="stdio")

trelix_mcp-0.5.0/tests/test_server.py

@@ -0,0 +1,215 @@
+"""Tests for trelix_mcp.server.
+
+Uses unittest.mock.patch to avoid touching real files or embedding models.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_mock_result(
+    file: str = "src/foo.py",
+    symbol: str = "foo.bar",
+    kind: str = "function",
+    line_start: int = 1,
+    line_end: int = 10,
+    score: float = 0.9,
+    source: str = "vector",
+    body: str = "def bar(): pass",
+    language: str = "python",
+) -> MagicMock:
+    """Return a mock SearchResult compatible with server.py expectations."""
+    r = MagicMock()
+    r.file.rel_path = file
+    r.file.language = language
+    r.symbol.qualified_name = symbol
+    r.symbol.kind = kind
+    r.symbol.line_start = line_start
+    r.symbol.line_end = line_end
+    r.symbol.body = body
+    r.score = score
+    r.source = source
+    return r
+
+
+def _make_mock_context(results: list[MagicMock]) -> MagicMock:
+    ctx = MagicMock()
+    ctx.results = results
+    return ctx
+
+
+# ---------------------------------------------------------------------------
+# Module import + basic structure
+# ---------------------------------------------------------------------------
+
+
+def test_server_importable() -> None:
+    import trelix_mcp.server as srv  # noqa: F401
+
+
+def test_mcp_attribute_exists() -> None:
+    import trelix_mcp.server as srv
+
+    assert hasattr(srv, "mcp"), "server.py must expose a top-level `mcp` object"
+
+
+def test_main_callable() -> None:
+    import trelix_mcp.server as srv
+
+    assert callable(srv.main)
+
+
+# ---------------------------------------------------------------------------
+# 4 tools registered
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_four_tools_registered() -> None:
+    import trelix_mcp.server as srv
+
+    tools = await srv.mcp.list_tools()
+    names = {t.name for t in tools}
+    assert {"search_code", "index_codebase", "get_symbol", "blast_radius"} == names, (
+        f"Expected exactly 4 tools, got: {names}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# search_code
+# ---------------------------------------------------------------------------
+
+
+def test_search_code_returns_list_of_dicts() -> None:
+    import trelix_mcp.server as srv
+
+    mock_results = [_make_mock_result()]
+    mock_ctx = _make_mock_context(mock_results)
+
+    with (
+        patch("trelix_mcp.server.IndexConfig"),
+        patch("trelix_mcp.server.Retriever") as MockRetriever,
+    ):
+        MockRetriever.return_value.retrieve.return_value = mock_ctx
+        results = srv.search_code("authentication", "/fake/repo", k=10)
+
+    assert isinstance(results, list)
+    assert len(results) == 1
+    item = results[0]
+    assert set(item.keys()) >= {
+        "file",
+        "symbol",
+        "kind",
+        "lines",
+        "score",
+        "source",
+        "body",
+        "language",
+    }
+
+
+def test_search_code_respects_k_limit() -> None:
+    """k=3 must truncate 20 mock results to 3."""
+    import trelix_mcp.server as srv
+
+    mock_results = [_make_mock_result(symbol=f"sym.{i}") for i in range(20)]
+    mock_ctx = _make_mock_context(mock_results)
+
+    with (
+        patch("trelix_mcp.server.IndexConfig"),
+        patch("trelix_mcp.server.Retriever") as MockRetriever,
+    ):
+        MockRetriever.return_value.retrieve.return_value = mock_ctx
+        results = srv.search_code("auth", "/fake/repo", k=3)
+
+    assert len(results) == 3
+
+
+# ---------------------------------------------------------------------------
+# index_codebase
+# ---------------------------------------------------------------------------
+
+
+def test_index_codebase_returns_dict() -> None:
+    import trelix_mcp.server as srv
+
+    fake_stats: dict[str, Any] = {
+        "files_found": 10,
+        "files_indexed": 8,
+        "files_skipped": 2,
+        "symbols_extracted": 50,
+        "chunks_total": 50,
+        "chunks_embedded": 50,
+        "errors": 0,
+        "elapsed_seconds": 1.23,
+    }
+
+    with (
+        patch("trelix_mcp.server.IndexConfig"),
+        patch("trelix_mcp.server.EmbedderConfig"),
+        patch("trelix_mcp.server.Indexer") as MockIndexer,
+    ):
+        MockIndexer.return_value.index.return_value = fake_stats
+        result = srv.index_codebase("/fake/repo", provider="local")
+
+    assert isinstance(result, dict)
+    assert result["files_found"] == 10
+
+
+# ---------------------------------------------------------------------------
+# blast_radius deduplication
+# ---------------------------------------------------------------------------
+
+
+def test_blast_radius_deduplicates_files() -> None:
+    """Two results sharing the same file should produce only one output entry."""
+    import trelix_mcp.server as srv
+
+    r1 = _make_mock_result(file="src/auth.py", symbol="auth.login")
+    r2 = _make_mock_result(file="src/auth.py", symbol="auth.logout")  # same file
+    r3 = _make_mock_result(file="src/db.py", symbol="db.connect")
+
+    mock_ctx = _make_mock_context([r1, r2, r3])
+
+    with (
+        patch("trelix_mcp.server.IndexConfig"),
+        patch("trelix_mcp.server.Retriever") as MockRetriever,
+    ):
+        MockRetriever.return_value.retrieve.return_value = mock_ctx
+        results = srv.blast_radius("auth", "/fake/repo")
+
+    files = [r["file"] for r in results]
+    assert len(files) == 2, f"Expected 2 unique files, got {files}"
+    assert "src/auth.py" in files
+    assert "src/db.py" in files
+
+
+# ---------------------------------------------------------------------------
+# CRITICAL: no stdout bytes on import
+# ---------------------------------------------------------------------------
+
+
+def test_server_import_produces_no_stdout(capsys: pytest.CaptureFixture[str]) -> None:
+    """Importing server.py must not write anything to stdout.
+
+    stdout is the MCP JSON protocol pipe — any spurious bytes corrupt the stream.
+    """
+    # Force a fresh import to catch any module-level print/write
+    if "trelix_mcp.server" in sys.modules:
+        del sys.modules["trelix_mcp.server"]
+
+    import trelix_mcp.server  # noqa: F401
+
+    captured = capsys.readouterr()
+    assert captured.out == "", (
+        f"server.py wrote {len(captured.out)} bytes to stdout on import: {captured.out!r}"
+    )