memgraph-ingester-mcp 0.1.0__tar.gz

memgraph_ingester_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --locked --dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Build
+        run: uv build --no-sources
+
+      - name: Publish
+        run: uv publish

memgraph_ingester_mcp-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.ruff_cache/
+.pytest_cache/
+.uv-cache/
+.venv/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.idea

memgraph_ingester_mcp-0.1.0/LICENSE

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

memgraph_ingester_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: memgraph-ingester-mcp
+Version: 0.1.0
+Summary: MCP tools for Memgraph graphs created by memgraph-ingester
+Project-URL: Homepage, https://github.com/ousatov-ua/memgraph-ingester-mcp
+Project-URL: Repository, https://github.com/ousatov-ua/memgraph-ingester-mcp
+Project-URL: Issues, https://github.com/ousatov-ua/memgraph-ingester-mcp/issues
+Author: Oleksii Usatov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: codex,knowledge-graph,mcp,memgraph,rag
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.16.0
+Requires-Dist: neo4j>=5.28.0
+Description-Content-Type: text/markdown
+
+# memgraph-ingester-mcp
+
+`memgraph-ingester-mcp` exposes safe, high-level MCP tools for Memgraph graphs produced by
+[`memgraph-ingester`](https://github.com/ousatov-ua/memgraph-ingester). It keeps agents out of long
+Cypher instruction blocks for normal work while still offering a project-scoped read-only Cypher
+escape hatch for unusual lookups.
+
+The package is intended to be published to PyPI as `memgraph-ingester-mcp` under the
+`ousatov-ua` account.
+
+## Tools
+
+Code graph tools:
+
+- `server_status`: graph inventory, memory counts, and vector index status.
+- `code_orientation`: compact package/type/call overview.
+- `code_search`: CodeChunk vector search for broad discovery.
+- `code_lookup_type`: exact class/interface/annotation lookup with members.
+- `code_lookup_methods`: exact method lookup with source ranges.
+- `code_callers`, `code_callees`: call graph lookups.
+- `code_hierarchy`: class ancestry, children, interfaces, and interface implementors.
+
+Memory tools:
+
+- `memory_orientation`: rules plus open findings, tasks, questions, and risks.
+- `memory_search`: MemoryChunk vector search with index-only hit metadata.
+- `memory_get`: canonical memory node plus resolved CodeRefs.
+- `memory_upsert`: create/update Decision, ADR, Rule, Context, Finding, Task, Risk, Question, or Idea.
+- `memory_update_status`: lifecycle status update.
+- `memory_link_code_ref`: link memory to a resolved CodeRef target.
+- `memory_refresh_chunk`, `memory_refresh_embeddings`: maintain derived memory RAG data.
+
+Fallback:
+
+- `raw_read_cypher`: read-only, project-scoped Cypher for edge cases.
+
+## Configuration
+
+Use namespaced environment variables so this server does not collide with generic shell settings:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `MEMGRAPH_INGESTER_MCP_BOLT_URI` | `bolt://127.0.0.1:7687` | Memgraph Bolt URI |
+| `MEMGRAPH_INGESTER_MCP_USERNAME` | unset | Optional username |
+| `MEMGRAPH_INGESTER_MCP_PASSWORD` | unset | Optional password |
+| `MEMGRAPH_INGESTER_MCP_DATABASE` | unset | Optional database name |
+| `MEMGRAPH_INGESTER_MCP_PROJECT` | unset | Default project name |
+| `MEMGRAPH_INGESTER_MCP_QUERY_TIMEOUT_SECONDS` | `30` | Query timeout |
+| `MEMGRAPH_INGESTER_MCP_READ_ONLY` | `false` | Disable write tools when `true` |
+| `MEMGRAPH_INGESTER_MCP_EMBEDDING_MODEL` | `default` | Metadata stamped on refreshed chunks |
+| `MEMGRAPH_INGESTER_MCP_EMBEDDING_DIMENSIONS` | `384` | Expected memory embedding dimension |
+
+## Run Locally
+
+```bash
+uv sync --dev
+uv run memgraph-ingester-mcp
+```
+
+Run tests:
+
+```bash
+uv run ruff check .
+uv run pytest
+```
+
+Build the package:
+
+```bash
+uv build --no-sources
+```
+
+## Client Setup
+
+Replace `my-project` with the project name used when running `memgraph-ingester`.
+
+### Codex
+
+Add this to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.memgraphIngester]
+command = "uvx"
+args = ["memgraph-ingester-mcp"]
+startup_timeout_ms = 20_000
+
+[mcp_servers.memgraphIngester.env]
+MEMGRAPH_INGESTER_MCP_BOLT_URI = "bolt://127.0.0.1:7687"
+MEMGRAPH_INGESTER_MCP_PROJECT = "my-project"
+```
+
+### Claude Desktop
+
+Add this to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "memgraphIngester": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["memgraph-ingester-mcp"],
+      "env": {
+        "MEMGRAPH_INGESTER_MCP_BOLT_URI": "bolt://127.0.0.1:7687",
+        "MEMGRAPH_INGESTER_MCP_PROJECT": "my-project"
+      }
+    }
+  }
+}
+```
+
+Claude Code can also add the same stdio server directly:
+
+```bash
+claude mcp add-json memgraphIngester \
+  '{"type":"stdio","command":"uvx","args":["memgraph-ingester-mcp"],"env":{"MEMGRAPH_INGESTER_MCP_BOLT_URI":"bolt://127.0.0.1:7687","MEMGRAPH_INGESTER_MCP_PROJECT":"my-project"}}'
+```
+
+### GitHub Copilot in VS Code
+
+Create `.vscode/mcp.json` in the workspace or add the server to your user MCP configuration:
+
+```json
+{
+  "servers": {
+    "memgraphIngester": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["memgraph-ingester-mcp"],
+      "env": {
+        "MEMGRAPH_INGESTER_MCP_BOLT_URI": "bolt://127.0.0.1:7687",
+        "MEMGRAPH_INGESTER_MCP_PROJECT": "my-project"
+      }
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add this to Gemini CLI `settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "memgraphIngester": {
+      "command": "uvx",
+      "args": ["memgraph-ingester-mcp"],
+      "env": {
+        "MEMGRAPH_INGESTER_MCP_BOLT_URI": "bolt://127.0.0.1:7687",
+        "MEMGRAPH_INGESTER_MCP_PROJECT": "my-project"
+      },
+      "trust": false
+    }
+  }
+}
+```
+
+## Agent Guidance
+
+Prefer the dedicated tools over `raw_read_cypher`. Use RAG search tools only for broad discovery,
+then follow up with exact lookup tools before making claims or edits. Use memory write tools for
+task lifecycle changes and CodeRef links so derived MemoryChunks stay refreshable.

memgraph_ingester_mcp-0.1.0/README.md

@@ -0,0 +1,163 @@
+# memgraph-ingester-mcp
+
+`memgraph-ingester-mcp` exposes safe, high-level MCP tools for Memgraph graphs produced by
+[`memgraph-ingester`](https://github.com/ousatov-ua/memgraph-ingester). It keeps agents out of long
+Cypher instruction blocks for normal work while still offering a project-scoped read-only Cypher
+escape hatch for unusual lookups.
+
+The package is intended to be published to PyPI as `memgraph-ingester-mcp` under the
+`ousatov-ua` account.
+
+## Tools
+
+Code graph tools:
+
+- `server_status`: graph inventory, memory counts, and vector index status.
+- `code_orientation`: compact package/type/call overview.
+- `code_search`: CodeChunk vector search for broad discovery.
+- `code_lookup_type`: exact class/interface/annotation lookup with members.
+- `code_lookup_methods`: exact method lookup with source ranges.
+- `code_callers`, `code_callees`: call graph lookups.
+- `code_hierarchy`: class ancestry, children, interfaces, and interface implementors.
+
+Memory tools:
+
+- `memory_orientation`: rules plus open findings, tasks, questions, and risks.
+- `memory_search`: MemoryChunk vector search with index-only hit metadata.
+- `memory_get`: canonical memory node plus resolved CodeRefs.
+- `memory_upsert`: create/update Decision, ADR, Rule, Context, Finding, Task, Risk, Question, or Idea.
+- `memory_update_status`: lifecycle status update.
+- `memory_link_code_ref`: link memory to a resolved CodeRef target.
+- `memory_refresh_chunk`, `memory_refresh_embeddings`: maintain derived memory RAG data.
+
+Fallback:
+
+- `raw_read_cypher`: read-only, project-scoped Cypher for edge cases.
+
+## Configuration
+
+Use namespaced environment variables so this server does not collide with generic shell settings:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `MEMGRAPH_INGESTER_MCP_BOLT_URI` | `bolt://127.0.0.1:7687` | Memgraph Bolt URI |
+| `MEMGRAPH_INGESTER_MCP_USERNAME` | unset | Optional username |
+| `MEMGRAPH_INGESTER_MCP_PASSWORD` | unset | Optional password |
+| `MEMGRAPH_INGESTER_MCP_DATABASE` | unset | Optional database name |
+| `MEMGRAPH_INGESTER_MCP_PROJECT` | unset | Default project name |
+| `MEMGRAPH_INGESTER_MCP_QUERY_TIMEOUT_SECONDS` | `30` | Query timeout |
+| `MEMGRAPH_INGESTER_MCP_READ_ONLY` | `false` | Disable write tools when `true` |
+| `MEMGRAPH_INGESTER_MCP_EMBEDDING_MODEL` | `default` | Metadata stamped on refreshed chunks |
+| `MEMGRAPH_INGESTER_MCP_EMBEDDING_DIMENSIONS` | `384` | Expected memory embedding dimension |
+
+## Run Locally
+
+```bash
+uv sync --dev
+uv run memgraph-ingester-mcp
+```
+
+Run tests:
+
+```bash
+uv run ruff check .
+uv run pytest
+```
+
+Build the package:
+
+```bash
+uv build --no-sources
+```
+
+## Client Setup
+
+Replace `my-project` with the project name used when running `memgraph-ingester`.
+
+### Codex
+
+Add this to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.memgraphIngester]
+command = "uvx"
+args = ["memgraph-ingester-mcp"]
+startup_timeout_ms = 20_000
+
+[mcp_servers.memgraphIngester.env]
+MEMGRAPH_INGESTER_MCP_BOLT_URI = "bolt://127.0.0.1:7687"
+MEMGRAPH_INGESTER_MCP_PROJECT = "my-project"
+```
+
+### Claude Desktop
+
+Add this to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "memgraphIngester": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["memgraph-ingester-mcp"],
+      "env": {
+        "MEMGRAPH_INGESTER_MCP_BOLT_URI": "bolt://127.0.0.1:7687",
+        "MEMGRAPH_INGESTER_MCP_PROJECT": "my-project"
+      }
+    }
+  }
+}
+```
+
+Claude Code can also add the same stdio server directly:
+
+```bash
+claude mcp add-json memgraphIngester \
+  '{"type":"stdio","command":"uvx","args":["memgraph-ingester-mcp"],"env":{"MEMGRAPH_INGESTER_MCP_BOLT_URI":"bolt://127.0.0.1:7687","MEMGRAPH_INGESTER_MCP_PROJECT":"my-project"}}'
+```
+
+### GitHub Copilot in VS Code
+
+Create `.vscode/mcp.json` in the workspace or add the server to your user MCP configuration:
+
+```json
+{
+  "servers": {
+    "memgraphIngester": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["memgraph-ingester-mcp"],
+      "env": {
+        "MEMGRAPH_INGESTER_MCP_BOLT_URI": "bolt://127.0.0.1:7687",
+        "MEMGRAPH_INGESTER_MCP_PROJECT": "my-project"
+      }
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add this to Gemini CLI `settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "memgraphIngester": {
+      "command": "uvx",
+      "args": ["memgraph-ingester-mcp"],
+      "env": {
+        "MEMGRAPH_INGESTER_MCP_BOLT_URI": "bolt://127.0.0.1:7687",
+        "MEMGRAPH_INGESTER_MCP_PROJECT": "my-project"
+      },
+      "trust": false
+    }
+  }
+}
+```
+
+## Agent Guidance
+
+Prefer the dedicated tools over `raw_read_cypher`. Use RAG search tools only for broad discovery,
+then follow up with exact lookup tools before making claims or edits. Use memory write tools for
+task lifecycle changes and CodeRef links so derived MemoryChunks stay refreshable.

memgraph_ingester_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "memgraph-ingester-mcp"
+version = "0.1.0"
+description = "MCP tools for Memgraph graphs created by memgraph-ingester"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Oleksii Usatov" }]
+keywords = ["mcp", "memgraph", "knowledge-graph", "rag", "codex"]
+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",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "mcp>=1.16.0",
+    "neo4j>=5.28.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ousatov-ua/memgraph-ingester-mcp"
+Repository = "https://github.com/ousatov-ua/memgraph-ingester-mcp"
+Issues = "https://github.com/ousatov-ua/memgraph-ingester-mcp/issues"
+
+[project.scripts]
+memgraph-ingester-mcp = "memgraph_ingester_mcp.server:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.0",
+    "ruff>=0.8.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/memgraph_ingester_mcp"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "C4", "RUF"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]

memgraph_ingester_mcp-0.1.0/src/memgraph_ingester_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP server for Memgraph Ingester graphs."""
+
+from memgraph_ingester_mcp.config import MemgraphConfig
+
+__all__ = ["MemgraphConfig"]

memgraph_ingester_mcp-0.1.0/src/memgraph_ingester_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Run the Memgraph Ingester MCP server."""
+
+from memgraph_ingester_mcp.server import main
+
+if __name__ == "__main__":
+    main()

memgraph_ingester_mcp-0.1.0/src/memgraph_ingester_mcp/config.py

@@ -0,0 +1,74 @@
+"""Runtime configuration for the MCP server."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from os import getenv
+
+
+def _optional_env(name: str) -> str | None:
+    value = getenv(name)
+    if value is None or value == "":
+        return None
+    return value
+
+
+def _bool_env(name: str, default: bool) -> bool:
+    value = getenv(name)
+    if value is None or value == "":
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _float_env(name: str, default: float) -> float:
+    value = getenv(name)
+    if value is None or value == "":
+        return default
+    return float(value)
+
+
+def _int_env(name: str, default: int) -> int:
+    value = getenv(name)
+    if value is None or value == "":
+        return default
+    return int(value)
+
+
+@dataclass(frozen=True)
+class MemgraphConfig:
+    """Namespaced Memgraph settings used by the stdio MCP process."""
+
+    bolt_uri: str = "bolt://127.0.0.1:7687"
+    username: str | None = None
+    password: str | None = None
+    database: str | None = None
+    default_project: str | None = None
+    query_timeout_seconds: float = 30.0
+    read_only: bool = False
+    embedding_model_name: str = "default"
+    embedding_dimensions: int = 384
+
+    @classmethod
+    def from_environment(cls) -> MemgraphConfig:
+        """Load only MCP-specific environment variables to avoid generic name collisions."""
+
+        return cls(
+            bolt_uri=getenv("MEMGRAPH_INGESTER_MCP_BOLT_URI", cls.bolt_uri),
+            username=_optional_env("MEMGRAPH_INGESTER_MCP_USERNAME"),
+            password=_optional_env("MEMGRAPH_INGESTER_MCP_PASSWORD"),
+            database=_optional_env("MEMGRAPH_INGESTER_MCP_DATABASE"),
+            default_project=_optional_env("MEMGRAPH_INGESTER_MCP_PROJECT"),
+            query_timeout_seconds=_float_env(
+                "MEMGRAPH_INGESTER_MCP_QUERY_TIMEOUT_SECONDS",
+                cls.query_timeout_seconds,
+            ),
+            read_only=_bool_env("MEMGRAPH_INGESTER_MCP_READ_ONLY", cls.read_only),
+            embedding_model_name=getenv(
+                "MEMGRAPH_INGESTER_MCP_EMBEDDING_MODEL",
+                cls.embedding_model_name,
+            ),
+            embedding_dimensions=_int_env(
+                "MEMGRAPH_INGESTER_MCP_EMBEDDING_DIMENSIONS",
+                cls.embedding_dimensions,
+            ),
+        )

memgraph_ingester_mcp-0.1.0/src/memgraph_ingester_mcp/db.py

@@ -0,0 +1,65 @@
+"""Thin Memgraph Bolt client."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import date, datetime
+from typing import Any
+
+from neo4j import GraphDatabase, Query
+from neo4j.time import Date, DateTime, Duration, Time
+
+from memgraph_ingester_mcp.config import MemgraphConfig
+
+
+class MemgraphError(RuntimeError):
+    """Raised when an MCP operation cannot be executed safely."""
+
+
+def _to_jsonable(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {str(key): _to_jsonable(item) for key, item in value.items()}
+    if isinstance(value, list | tuple):
+        return [_to_jsonable(item) for item in value]
+    if isinstance(value, DateTime | Date | Time | Duration | datetime | date):
+        return str(value)
+    return value
+
+
+class MemgraphClient:
+    """Execute parameterized Cypher against Memgraph over Bolt."""
+
+    def __init__(self, config: MemgraphConfig, driver: Any | None = None) -> None:
+        self.config = config
+        if driver is None:
+            auth = None
+            if config.username is not None:
+                auth = (config.username, config.password or "")
+            driver = GraphDatabase.driver(config.bolt_uri, auth=auth)
+        self._driver = driver
+
+    def close(self) -> None:
+        close = getattr(self._driver, "close", None)
+        if close is not None:
+            close()
+
+    def run(
+        self,
+        query: str,
+        parameters: Mapping[str, Any] | None = None,
+        *,
+        write: bool = False,
+    ) -> list[dict[str, Any]]:
+        if write and self.config.read_only:
+            raise MemgraphError("Write tools are disabled by MEMGRAPH_INGESTER_MCP_READ_ONLY.")
+
+        session_kwargs: dict[str, Any] = {}
+        if self.config.database is not None:
+            session_kwargs["database"] = self.config.database
+
+        with self._driver.session(**session_kwargs) as session:
+            result = session.run(
+                Query(query, timeout=self.config.query_timeout_seconds),
+                dict(parameters or {}),
+            )
+            return [_to_jsonable(dict(record)) for record in result]