codex-lsp-mcp 0.1.0__tar.gz

codex_lsp_mcp-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+*.py[cod]
+uv.lock

codex_lsp_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: codex-lsp-mcp
+Version: 0.1.0
+Summary: MCP server exposing read-only LSP navigation tools for Codex
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# codex-lsp-mcp
+
+`codex-lsp-mcp` is a local MCP stdio server that exposes read-only LSP navigation tools to Codex.
+
+First supported backend: `clangd`.
+
+## Local development
+
+```bash
+uv run pytest
+uvx --from . codex-lsp-mcp
+```
+
+## Codex configuration
+
+```bash
+codex mcp add codex-lsp-mcp -- uvx --from git+https://github.com/SunJun8/codex-lsp-mcp.git@v0.1.0 codex-lsp-mcp
+```
+
+Check registration:
+
+```bash
+codex mcp get codex-lsp-mcp
+```
+
+If `clangd` is not on Codex's `PATH`, set:
+
+```toml
+[mcp_servers.codex-lsp-mcp.env]
+CLANGD_BIN = "/path/to/clangd"
+```
+
+The server discovers the closest `compile_commands.json` from the queried file path.
+
+Tool coordinates follow the LSP convention: zero-based `line` and `character`.

codex_lsp_mcp-0.1.0/README.md

@@ -0,0 +1,35 @@
+# codex-lsp-mcp
+
+`codex-lsp-mcp` is a local MCP stdio server that exposes read-only LSP navigation tools to Codex.
+
+First supported backend: `clangd`.
+
+## Local development
+
+```bash
+uv run pytest
+uvx --from . codex-lsp-mcp
+```
+
+## Codex configuration
+
+```bash
+codex mcp add codex-lsp-mcp -- uvx --from git+https://github.com/SunJun8/codex-lsp-mcp.git@v0.1.0 codex-lsp-mcp
+```
+
+Check registration:
+
+```bash
+codex mcp get codex-lsp-mcp
+```
+
+If `clangd` is not on Codex's `PATH`, set:
+
+```toml
+[mcp_servers.codex-lsp-mcp.env]
+CLANGD_BIN = "/path/to/clangd"
+```
+
+The server discovers the closest `compile_commands.json` from the queried file path.
+
+Tool coordinates follow the LSP convention: zero-based `line` and `character`.

codex_lsp_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codex-lsp-mcp"
+version = "0.1.0"
+description = "MCP server exposing read-only LSP navigation tools for Codex"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "mcp>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.23.0",
+]
+
+[project.scripts]
+codex-lsp-mcp = "codex_lsp_mcp.server:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

codex_lsp_mcp-0.1.0/src/codex_lsp_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server exposing read-only LSP navigation tools."""
+
+__version__ = "0.1.0"

codex_lsp_mcp-0.1.0/src/codex_lsp_mcp/config.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from pathlib import Path
+import os
+import shlex
+import tomllib
+
+
+DEFAULT_CONFIG_PATH = Path.home() / ".config" / "codex-lsp-mcp" / "config.toml"
+
+
+@dataclass(frozen=True)
+class ServerConfig:
+    command: str
+    args: list[str]
+    extension_to_language: dict[str, str]
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    servers: dict[str, ServerConfig]
+
+
+def default_config() -> AppConfig:
+    return AppConfig(
+        servers={
+            "clangd": ServerConfig(
+                command="clangd",
+                args=["--background-index"],
+                extension_to_language={
+                    ".c": "c",
+                    ".h": "c",
+                    ".cpp": "cpp",
+                    ".cc": "cpp",
+                    ".cxx": "cpp",
+                    ".hpp": "cpp",
+                    ".hxx": "cpp",
+                    ".C": "cpp",
+                    ".H": "cpp",
+                },
+            )
+        }
+    )
+
+
+def load_config(env: dict[str, str] | None = None) -> AppConfig:
+    values = dict(os.environ if env is None else env)
+    config = default_config()
+
+    config_path = Path(values.get("CODEX_LSP_MCP_CONFIG", DEFAULT_CONFIG_PATH)).expanduser()
+    if config_path.exists():
+        config = _merge_config_file(config, config_path)
+
+    clangd = config.servers["clangd"]
+    if "CLANGD_BIN" in values:
+        clangd = replace(clangd, command=values["CLANGD_BIN"])
+    if "CLANGD_ARGS" in values:
+        clangd = replace(clangd, args=shlex.split(values["CLANGD_ARGS"]))
+
+    servers = dict(config.servers)
+    servers["clangd"] = clangd
+    return AppConfig(servers=servers)
+
+
+def _merge_config_file(config: AppConfig, path: Path) -> AppConfig:
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    servers = dict(config.servers)
+
+    for name, raw_server in data.get("servers", {}).items():
+        existing = servers.get(name, ServerConfig(command=name, args=[], extension_to_language={}))
+        extension_to_language = raw_server.get(
+            "extension_to_language", existing.extension_to_language
+        )
+        servers[name] = ServerConfig(
+            command=raw_server.get("command", existing.command),
+            args=list(raw_server.get("args", existing.args)),
+            extension_to_language=dict(extension_to_language),
+        )
+
+    return AppConfig(servers=servers)

codex_lsp_mcp-0.1.0/src/codex_lsp_mcp/lsp.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+from collections.abc import Callable
+from typing import Any
+
+
+JsonObject = dict[str, Any]
+ServerRequestHandler = Callable[[JsonObject], Any]
+
+
+class LspConnectionError(ConnectionError):
+    pass
+
+
+class LspProtocolError(RuntimeError):
+    pass
+
+
+def encode_message(message: JsonObject) -> bytes:
+    body = json.dumps(message, separators=(",", ":")).encode("utf-8")
+    header = f"Content-Length: {len(body)}\r\n\r\n".encode("ascii")
+    return header + body
+
+
+async def read_message(reader: asyncio.StreamReader) -> JsonObject:
+    headers: dict[str, str] = {}
+    while True:
+        line = await reader.readline()
+        if line == b"":
+            raise LspConnectionError("connection closed while reading headers")
+        if line in (b"\r\n", b"\n"):
+            break
+        if b":" not in line:
+            raise LspProtocolError(f"malformed header: {line.decode('ascii', errors='replace').strip()}")
+        key, value = line.decode("ascii").split(":", 1)
+        headers[key.lower()] = value.strip()
+
+    if "content-length" not in headers:
+        raise LspProtocolError("missing Content-Length header")
+    try:
+        length = int(headers["content-length"])
+    except ValueError as exc:
+        raise LspProtocolError("invalid Content-Length header") from exc
+    if length < 0:
+        raise LspProtocolError("invalid Content-Length header")
+
+    try:
+        body = await reader.readexactly(length)
+    except asyncio.IncompleteReadError as exc:
+        raise LspConnectionError("connection closed while reading body") from exc
+
+    try:
+        return json.loads(body.decode("utf-8"))
+    except json.JSONDecodeError as exc:
+        raise LspProtocolError("invalid JSON-RPC message body") from exc
+
+
+class LspClient:
+    def __init__(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        self._reader = reader
+        self._writer = writer
+        self._next_id = 1
+        self._pending: dict[int, asyncio.Future[JsonObject]] = {}
+        self._request_handlers: dict[str, ServerRequestHandler] = {}
+        self._notifications: asyncio.Queue[JsonObject] = asyncio.Queue()
+        self._notification_waiters: set[asyncio.Future[JsonObject]] = set()
+        self._reader_task: asyncio.Task[None] | None = None
+        self._closed_error: Exception | None = None
+
+    def start(self) -> None:
+        self._reader_task = asyncio.create_task(self._read_loop())
+
+    def set_request_handler(self, method: str, handler: ServerRequestHandler) -> None:
+        self._request_handlers[method] = handler
+
+    async def stop(self) -> None:
+        self._closed_error = LspConnectionError("LSP client stopped")
+        self._fail_pending(self._closed_error)
+        if self._reader_task is not None:
+            self._reader_task.cancel()
+            try:
+                await self._reader_task
+            except asyncio.CancelledError:
+                pass
+        self._writer.close()
+        await self._writer.wait_closed()
+
+    async def request(self, method: str, params: JsonObject | None = None) -> Any:
+        self._raise_if_closed()
+        request_id = self._next_id
+        self._next_id += 1
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[JsonObject] = loop.create_future()
+        self._pending[request_id] = future
+        try:
+            await self._write({"jsonrpc": "2.0", "id": request_id, "method": method, "params": params or {}})
+            response = await future
+            if "error" in response:
+                raise RuntimeError(response["error"])
+            return response.get("result")
+        except asyncio.CancelledError:
+            self._pending.pop(request_id, None)
+            if self._closed_error is None:
+                await self._write_unchecked({"jsonrpc": "2.0", "method": "$/cancelRequest", "params": {"id": request_id}})
+            raise
+        finally:
+            self._pending.pop(request_id, None)
+
+    async def notify(self, method: str, params: JsonObject | None = None) -> None:
+        self._raise_if_closed()
+        await self._write({"jsonrpc": "2.0", "method": method, "params": params or {}})
+
+    async def next_notification(self) -> JsonObject:
+        self._raise_if_closed()
+        if not self._notifications.empty():
+            return await self._notifications.get()
+
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[JsonObject] = loop.create_future()
+        self._notification_waiters.add(future)
+        try:
+            return await future
+        finally:
+            self._notification_waiters.discard(future)
+
+    async def _write(self, message: JsonObject) -> None:
+        self._raise_if_closed()
+        await self._write_unchecked(message)
+
+    async def _write_unchecked(self, message: JsonObject) -> None:
+        self._writer.write(encode_message(message))
+        await self._writer.drain()
+
+    async def _read_loop(self) -> None:
+        try:
+            while True:
+                message = await read_message(self._reader)
+                await self._handle_message(message)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            self._closed_error = exc
+            self._fail_pending(exc)
+
+    async def _handle_message(self, message: JsonObject) -> None:
+        message_id = message.get("id")
+        if "id" in message and "method" in message:
+            await self._handle_server_request(message_id, message)
+        elif isinstance(message_id, int) and message_id in self._pending:
+            future = self._pending.pop(message_id)
+            if not future.done():
+                future.set_result(message)
+        elif "id" in message:
+            return
+        else:
+            self._put_notification(message)
+
+    async def _handle_server_request(self, message_id: Any, message: JsonObject) -> None:
+        method = message.get("method")
+        handler = self._request_handlers.get(method)
+        if handler is None:
+            await self._write(
+                {
+                    "jsonrpc": "2.0",
+                    "id": message_id,
+                    "error": {"code": -32601, "message": "Method not found"},
+                }
+            )
+            return
+
+        try:
+            result = handler(message.get("params", {}))
+            if inspect.isawaitable(result):
+                result = await result
+        except Exception as exc:
+            await self._write(
+                {
+                    "jsonrpc": "2.0",
+                    "id": message_id,
+                    "error": {"code": -32000, "message": str(exc)},
+                }
+            )
+            return
+
+        await self._write({"jsonrpc": "2.0", "id": message_id, "result": result})
+
+    def _raise_if_closed(self) -> None:
+        if self._closed_error is not None:
+            raise self._closed_error
+
+    def _fail_pending(self, exc: Exception) -> None:
+        pending = list(self._pending.values())
+        self._pending.clear()
+        for future in pending:
+            if not future.done():
+                future.set_exception(exc)
+        self._fail_notification_waiters(exc)
+
+    def _put_notification(self, message: JsonObject) -> None:
+        for future in list(self._notification_waiters):
+            self._notification_waiters.discard(future)
+            if not future.done():
+                future.set_result(message)
+                return
+        self._notifications.put_nowait(message)
+
+    def _fail_notification_waiters(self, exc: Exception) -> None:
+        waiters = list(self._notification_waiters)
+        self._notification_waiters.clear()
+        for future in waiters:
+            if not future.done():
+                future.set_exception(exc)

codex_lsp_mcp-0.1.0/src/codex_lsp_mcp/manager.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable
+
+from .config import AppConfig, ServerConfig
+from .root import discover_root
+from .session import ClangdSession
+
+
+SessionFactory = Callable[[Path, ServerConfig], ClangdSession]
+
+
+class SessionManager:
+    def __init__(
+        self,
+        config: AppConfig,
+        fallback_root: str | Path,
+        session_factory: SessionFactory = ClangdSession,
+    ) -> None:
+        self.config = config
+        self.fallback_root = Path(fallback_root).expanduser().resolve()
+        self.session_factory = session_factory
+        self.sessions: dict[tuple[str, Path], ClangdSession] = {}
+
+    def get_session(self, file_path: str | Path) -> ClangdSession:
+        path = Path(file_path).expanduser().resolve()
+        server_name, _language_id = self.language_for(path)
+        root = discover_root(path, self.fallback_root)
+        key = (server_name, root)
+        if key not in self.sessions:
+            self.sessions[key] = self.session_factory(root, self.config.servers[server_name])
+        return self.sessions[key]
+
+    def language_for(self, file_path: str | Path) -> tuple[str, str]:
+        path = Path(file_path)
+        for server_name, server_config in self.config.servers.items():
+            language_id = server_config.extension_to_language.get(path.suffix)
+            if language_id:
+                return server_name, language_id
+        raise ValueError(f"unsupported file extension: {path.suffix}")

codex_lsp_mcp-0.1.0/src/codex_lsp_mcp/preview.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def make_position(line: int, character: int) -> dict[str, int]:
+    if line < 0 or character < 0:
+        raise ValueError("line and character must be zero-based non-negative integers")
+    return {"line": line, "character": character}
+
+
+def lsp_range_to_user_range(lsp_range: dict[str, Any]) -> dict[str, int]:
+    start = lsp_range["start"]
+    end = lsp_range["end"]
+    return {
+        "line": start["line"],
+        "character": start["character"],
+        "end_line": end["line"],
+        "end_character": end["character"],
+    }
+
+
+def read_preview(path: str | Path, line: int) -> str:
+    if line < 1:
+        return ""
+    file_path = Path(path)
+    try:
+        lines = file_path.read_text(encoding="utf-8", errors="replace").splitlines()
+    except FileNotFoundError:
+        return ""
+    if line > len(lines):
+        return ""
+    return lines[line - 1].strip()

codex_lsp_mcp-0.1.0/src/codex_lsp_mcp/root.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+ROOT_MARKER_GROUPS = (
+    ("compile_commands.json",),
+    ("compile_flags.txt",),
+    (".clangd",),
+    (".git", ".repo"),
+)
+
+
+def discover_root(file_path: str | Path, fallback: str | Path) -> Path:
+    path = Path(file_path).expanduser().resolve()
+    current = path.parent if path.is_file() or path.suffix else path
+    fallback_path = Path(fallback).expanduser().resolve()
+    ancestors = [current, *current.parents]
+
+    for markers in ROOT_MARKER_GROUPS:
+        for directory in ancestors:
+            if any((directory / marker).exists() for marker in markers):
+                return directory
+
+    return fallback_path

codex_lsp_mcp-0.1.0/src/codex_lsp_mcp/server.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from .config import load_config
+from .manager import SessionManager
+
+
+JsonObject = dict[str, Any]
+
+
+class ToolHandlers:
+    def __init__(self, manager: SessionManager) -> None:
+        self.manager = manager
+
+    async def definition(self, file: str, line: int, character: int) -> JsonObject:
+        """Return definition locations for a zero-based LSP position."""
+        path, language_id, session = self._resolve_file(file)
+        return await session.definition(path, language_id, line, character)
+
+    async def references(
+        self,
+        file: str,
+        line: int,
+        character: int,
+        include_declaration: bool = False,
+    ) -> JsonObject:
+        """Return references for a zero-based LSP position."""
+        path, language_id, session = self._resolve_file(file)
+        return await session.references(
+            path,
+            language_id,
+            line,
+            character,
+            include_declaration,
+        )
+
+    async def hover(self, file: str, line: int, character: int) -> JsonObject:
+        """Return hover text for a zero-based LSP position."""
+        path, language_id, session = self._resolve_file(file)
+        return await session.hover(path, language_id, line, character)
+
+    async def diagnostics(self, file: str) -> JsonObject:
+        """Return diagnostics for a file."""
+        path, language_id, session = self._resolve_file(file)
+        return await session.diagnostics(path, language_id)
+
+    async def document_symbols(self, file: str) -> JsonObject:
+        """Return document symbols for a file."""
+        path, language_id, session = self._resolve_file(file)
+        return await session.document_symbols(path, language_id)
+
+    async def workspace_symbols(
+        self,
+        query: str,
+        root_hint: str | None = None,
+    ) -> JsonObject:
+        """Return workspace symbols, optionally scoped by a root hint."""
+        if root_hint is not None:
+            hint = Path(root_hint).expanduser().resolve()
+            session_path = hint if hint.is_file() else hint / ".codex_lsp_workspace_hint.c"
+            session = self.manager.get_session(session_path)
+        else:
+            try:
+                session = next(iter(self.manager.sessions.values()))
+            except StopIteration:
+                session_path = self.manager.fallback_root / ".codex_lsp_workspace_hint.c"
+                session = self.manager.get_session(session_path)
+        return await session.workspace_symbols(query)
+
+    def _resolve_file(self, file: str) -> tuple[Path, str, Any]:
+        path = Path(file).expanduser().resolve()
+        if not path.exists():
+            raise FileNotFoundError(path)
+
+        _server_name, language_id = self.manager.language_for(path)
+        session = self.manager.get_session(path)
+        return path, language_id, session
+
+
+def build_mcp() -> FastMCP:
+    config = load_config()
+    manager = SessionManager(config, fallback_root=Path.cwd())
+    handlers = ToolHandlers(manager)
+    mcp = FastMCP("codex-lsp-mcp")
+
+    mcp.tool()(handlers.definition)
+    mcp.tool()(handlers.references)
+    mcp.tool()(handlers.hover)
+    mcp.tool()(handlers.diagnostics)
+    mcp.tool()(handlers.document_symbols)
+    mcp.tool()(handlers.workspace_symbols)
+
+    return mcp
+
+
+def main() -> None:
+    build_mcp().run()