dataxplan-mcp 0.1.0__tar.gz

dataxplan_mcp-0.1.0/LICENSE

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

dataxplan_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: dataxplan-mcp
+Version: 0.1.0
+Summary: MCP server for dataxplan: read PostgreSQL EXPLAIN plans for AI agents (bottlenecks, estimation errors, fixes, charts).
+Author: Atakan Arikan
+License: MIT
+Project-URL: Homepage, https://github.com/arikanatakan/dataxplan-mcp
+Project-URL: Repository, https://github.com/arikanatakan/dataxplan-mcp
+Project-URL: Issues, https://github.com/arikanatakan/dataxplan-mcp/issues
+Project-URL: Library, https://github.com/arikanatakan/dataxplan
+Keywords: mcp,model-context-protocol,ai-agents,postgresql,postgres,explain,query-plan,performance,query-optimization,database
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dataxplan[viz,yaml]>=0.1.3
+Requires-Dist: mcp>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+<!-- mcp-name: io.github.arikanatakan/dataxplan-mcp -->
+
+# dataxplan-mcp
+
+[![CI](https://github.com/arikanatakan/dataxplan-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/arikanatakan/dataxplan-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/dataxplan-mcp)](https://pypi.org/project/dataxplan-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+An MCP server that exposes [dataxplan](https://github.com/arikanatakan/dataxplan),
+the PostgreSQL EXPLAIN-plan analyzer for Python, as tools for AI agents: give it
+the output of `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` and it returns the
+bottlenecks, the estimation errors, documented findings with a suggested action
+and a source reference, a regression comparison, and a self-time chart.
+
+Agents asked why a query is slow tend to eyeball the plan and get it wrong: self
+time is per loop and inclusive of children, so the slow node is rarely the
+obvious one, and a row mis-estimate (the usual root cause) is buried in the
+output. Reading the plan belongs in a deterministic, versioned library that the
+agent calls, which leaves the agent to interpret the result and decide. The
+server never connects to a database: the agent runs EXPLAIN and passes the
+output, so nothing leaves its environment.
+
+![dataxplan-mcp architecture: an AI agent calls the server's analysis and chart tools, which route to the validated dataxplan core and return structured JSON or a PNG chart](assets/architecture.png)
+
+## Tools
+
+**Analysis tools** return dataxplan's payload: the metrics, the findings (each
+with a severity, a suggestion and a documented source reference) and a summary.
+
+| Tool | Purpose |
+| ---- | ------- |
+| `analyze_plan` | bottlenecks, estimation errors and findings from an EXPLAIN plan (JSON, text, YAML or XML) |
+| `compare_plans` | compare two plans for regression (timing, shape, estimates, findings) |
+| `plan_tree` | the plan as an annotated text tree (self time, rows, flags per node) |
+| `describe_inputs` | how to produce the plan, the accepted formats, the findings and the thresholds |
+
+**Chart tools** return a PNG image.
+
+| Tool | Purpose |
+| ---- | ------- |
+| `plan_chart` | self time per node, with the high-severity findings highlighted |
+
+All tools are read-only, and the server makes no database connection.
+
+## Installation
+
+Run it with [uv](https://docs.astral.sh/uv/) (no install needed):
+
+```
+uvx dataxplan-mcp
+```
+
+or install from PyPI:
+
+```
+pip install dataxplan-mcp
+```
+
+## Configuration
+
+Add it to your MCP client. For example:
+
+```json
+{
+  "mcpServers": {
+    "dataxplan": {
+      "command": "uvx",
+      "args": ["dataxplan-mcp"]
+    }
+  }
+}
+```
+
+If you installed with pip, use `"command": "dataxplan-mcp"` with no args.
+
+## Example
+
+```
+analyze_plan(plan="<EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) output>")
+  -> { "summary_metrics": { "execution_time_ms": 1240.0,
+                            "max_estimation_error": 20000, ... },
+       "findings": [ { "id": "seq_scan_hot", "severity": "high",
+                       "detail": "... 95% of execution time ...",
+                       "suggestion": "consider an index ...",
+                       "reference": "PostgreSQL: Using EXPLAIN; the Indexes chapter" } ],
+       "summary": "dataxplan - ...\n  execution time ..." }
+```
+
+The agent runs the EXPLAIN itself and pastes the output (any format) as `plan`.
+
+## Design
+
+The server is a thin, stateless wrapper. All of the analysis lives in the
+dataxplan library, which computes the metrics from the documented EXPLAIN fields
+and grounds each finding in the PostgreSQL manual (and Leis et al. 2015 for the
+estimation rules). The server adds the tool schema, read-only annotations and an
+input-schema helper so an agent can format the input and act on the result. The
+findings are documented heuristics, not guarantees, and the server connects to
+nothing.
+
+## Related
+
+- [dataxplan](https://github.com/arikanatakan/dataxplan): the library this server
+  wraps.
+
+## License
+
+MIT. Written and maintained by [Atakan Arikan](https://github.com/arikanatakan),
+MSc Student at Tsinghua University and Politecnico di Milano.

dataxplan_mcp-0.1.0/README.md

@@ -0,0 +1,109 @@
+<!-- mcp-name: io.github.arikanatakan/dataxplan-mcp -->
+
+# dataxplan-mcp
+
+[![CI](https://github.com/arikanatakan/dataxplan-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/arikanatakan/dataxplan-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/dataxplan-mcp)](https://pypi.org/project/dataxplan-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+An MCP server that exposes [dataxplan](https://github.com/arikanatakan/dataxplan),
+the PostgreSQL EXPLAIN-plan analyzer for Python, as tools for AI agents: give it
+the output of `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` and it returns the
+bottlenecks, the estimation errors, documented findings with a suggested action
+and a source reference, a regression comparison, and a self-time chart.
+
+Agents asked why a query is slow tend to eyeball the plan and get it wrong: self
+time is per loop and inclusive of children, so the slow node is rarely the
+obvious one, and a row mis-estimate (the usual root cause) is buried in the
+output. Reading the plan belongs in a deterministic, versioned library that the
+agent calls, which leaves the agent to interpret the result and decide. The
+server never connects to a database: the agent runs EXPLAIN and passes the
+output, so nothing leaves its environment.
+
+![dataxplan-mcp architecture: an AI agent calls the server's analysis and chart tools, which route to the validated dataxplan core and return structured JSON or a PNG chart](assets/architecture.png)
+
+## Tools
+
+**Analysis tools** return dataxplan's payload: the metrics, the findings (each
+with a severity, a suggestion and a documented source reference) and a summary.
+
+| Tool | Purpose |
+| ---- | ------- |
+| `analyze_plan` | bottlenecks, estimation errors and findings from an EXPLAIN plan (JSON, text, YAML or XML) |
+| `compare_plans` | compare two plans for regression (timing, shape, estimates, findings) |
+| `plan_tree` | the plan as an annotated text tree (self time, rows, flags per node) |
+| `describe_inputs` | how to produce the plan, the accepted formats, the findings and the thresholds |
+
+**Chart tools** return a PNG image.
+
+| Tool | Purpose |
+| ---- | ------- |
+| `plan_chart` | self time per node, with the high-severity findings highlighted |
+
+All tools are read-only, and the server makes no database connection.
+
+## Installation
+
+Run it with [uv](https://docs.astral.sh/uv/) (no install needed):
+
+```
+uvx dataxplan-mcp
+```
+
+or install from PyPI:
+
+```
+pip install dataxplan-mcp
+```
+
+## Configuration
+
+Add it to your MCP client. For example:
+
+```json
+{
+  "mcpServers": {
+    "dataxplan": {
+      "command": "uvx",
+      "args": ["dataxplan-mcp"]
+    }
+  }
+}
+```
+
+If you installed with pip, use `"command": "dataxplan-mcp"` with no args.
+
+## Example
+
+```
+analyze_plan(plan="<EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) output>")
+  -> { "summary_metrics": { "execution_time_ms": 1240.0,
+                            "max_estimation_error": 20000, ... },
+       "findings": [ { "id": "seq_scan_hot", "severity": "high",
+                       "detail": "... 95% of execution time ...",
+                       "suggestion": "consider an index ...",
+                       "reference": "PostgreSQL: Using EXPLAIN; the Indexes chapter" } ],
+       "summary": "dataxplan - ...\n  execution time ..." }
+```
+
+The agent runs the EXPLAIN itself and pastes the output (any format) as `plan`.
+
+## Design
+
+The server is a thin, stateless wrapper. All of the analysis lives in the
+dataxplan library, which computes the metrics from the documented EXPLAIN fields
+and grounds each finding in the PostgreSQL manual (and Leis et al. 2015 for the
+estimation rules). The server adds the tool schema, read-only annotations and an
+input-schema helper so an agent can format the input and act on the result. The
+findings are documented heuristics, not guarantees, and the server connects to
+nothing.
+
+## Related
+
+- [dataxplan](https://github.com/arikanatakan/dataxplan): the library this server
+  wraps.
+
+## License
+
+MIT. Written and maintained by [Atakan Arikan](https://github.com/arikanatakan),
+MSc Student at Tsinghua University and Politecnico di Milano.

dataxplan_mcp-0.1.0/dataxplan_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""dataxplan-mcp: an MCP server exposing the dataxplan EXPLAIN-plan analyzer."""
+
+from ._version import __version__
+
+__all__ = ["__version__"]

dataxplan_mcp-0.1.0/dataxplan_mcp/_tools.py

@@ -0,0 +1,137 @@
+"""Tool logic, kept free of the MCP SDK so it can be tested directly.
+
+Each tool calls the dataxplan library on the EXPLAIN plan the agent supplies and
+returns its JSON-safe payload (metrics, findings with a suggestion and a source
+reference) plus a plain-language summary. The server never connects to a
+database: the agent runs EXPLAIN and passes the output here.
+"""
+
+from __future__ import annotations
+
+import io
+
+import matplotlib
+
+matplotlib.use("Agg")
+
+import dataxplan  # noqa: E402
+from dataxplan.findings import DEFAULT_THRESHOLDS  # noqa: E402
+from pydantic import BaseModel, Field  # noqa: E402
+
+_HINT = "call describe_inputs for how to produce the plan and the accepted formats"
+
+FINDINGS = {
+    "estimate_off": "the actual rows are far from the estimate (the usual root "
+                    "cause of a bad plan)",
+    "seq_scan_hot": "a sequential scan is a large share of a non-trivial query's time",
+    "disk_spill": "a sort or hash spilled to disk (work_mem too small)",
+    "filter_discard": "a scan read many rows and kept few (non-sargable or a "
+                      "missing index)",
+    "nested_loop_blowup": "a nested loop ran its inner side many times and it cost "
+                          "real time",
+    "index_only_heap_fetches": "an index-only scan still hit the heap (the table "
+                               "needs VACUUM)",
+    "lossy_bitmap": "a bitmap heap scan went lossy (work_mem too small)",
+    "jit_overhead": "JIT compilation was a large share of a short query's time",
+}
+
+NOTES = (
+    "The findings are documented heuristics, not guarantees, and the analysis is "
+    "of the plan you provide: the server does not connect to a database, run your "
+    "query or read your schema. Self times for parallel plans are total work "
+    "across workers, not wall-clock time. Run EXPLAIN with ANALYZE for timing."
+)
+
+
+class TableInfoInput(BaseModel):
+    """Optional catalog facts about one table."""
+
+    row_count: float | None = Field(default=None, description="Approximate row count.")
+    indexed_columns: list[str] = Field(
+        default_factory=list, description="Columns that appear in some index.")
+    analyzed: bool = Field(default=True, description="False if statistics look stale.")
+
+
+class ContextInput(BaseModel):
+    """Optional catalog context that sharpens the findings."""
+
+    tables: dict[str, TableInfoInput] = Field(
+        default_factory=dict, description="Table name -> catalog facts.")
+    work_mem_mb: float | None = Field(default=None, description="The server's work_mem in MB.")
+
+
+def _context(context: ContextInput | None):
+    if context is None:
+        return None
+    return {
+        "tables": {
+            name: {"row_count": t.row_count,
+                   "indexed_columns": tuple(t.indexed_columns),
+                   "analyzed": t.analyzed}
+            for name, t in context.tables.items()
+        },
+        "work_mem_mb": context.work_mem_mb,
+    }
+
+
+def _payload(result) -> dict:
+    out = result.to_dict()
+    out["summary"] = result.summary()
+    return out
+
+
+def analyze_plan(plan: str, context: ContextInput | None = None,
+                 thresholds: dict[str, float] | None = None) -> dict:
+    """Analyse a PostgreSQL EXPLAIN plan: bottlenecks, estimation errors and findings.
+
+    ``plan`` is the output of ``EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) ...`` (text,
+    YAML and XML are also accepted). Optional ``context`` (table sizes, indexed
+    columns, stale stats) sharpens the findings; ``thresholds`` overrides the rule
+    cut-offs (see describe_inputs).
+    """
+    try:
+        report = dataxplan.analyze(plan, _context(context), thresholds=thresholds)
+        return _payload(report)
+    except (ValueError, TypeError, ImportError) as exc:
+        return {"error": str(exc), "hint": _HINT}
+
+
+def compare_plans(before: str, after: str) -> dict:
+    """Compare two plans for regression: timing, plan shape, estimates and findings."""
+    try:
+        return _payload(dataxplan.compare(before, after))
+    except (ValueError, TypeError) as exc:
+        return {"error": str(exc), "hint": _HINT}
+
+
+def plan_tree(plan: str) -> str:
+    """The plan as an annotated text tree (self time, rows, flags per node)."""
+    try:
+        return dataxplan.text_tree(dataxplan.analyze(plan))
+    except (ValueError, TypeError) as exc:
+        return f"error: {exc}\n({_HINT})"
+
+
+def describe_inputs() -> dict:
+    """How to produce the plan, the accepted formats, the findings and thresholds."""
+    return {
+        "how_to": "Run EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) <query> and pass "
+                  "its output as `plan`. ANALYZE adds the real times and row "
+                  "counts (needed for self time and most findings); BUFFERS adds "
+                  "the block counts.",
+        "accepted_formats": ["JSON (exact)", "text (best-effort)", "YAML", "XML"],
+        "findings": FINDINGS,
+        "thresholds": DEFAULT_THRESHOLDS,
+        "notes": NOTES,
+    }
+
+
+def plan_png(plan: str) -> bytes:
+    """Render the self-time-per-node chart as PNG bytes."""
+    report = dataxplan.analyze(plan)
+    fig = dataxplan.plan_tree_chart(report)
+    buffer = io.BytesIO()
+    fig.savefig(buffer, format="png", dpi=150, bbox_inches="tight", facecolor="white")
+    import matplotlib.pyplot as plt
+    plt.close(fig)
+    return buffer.getvalue()

dataxplan_mcp-0.1.0/dataxplan_mcp/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

dataxplan_mcp-0.1.0/dataxplan_mcp/server.py

@@ -0,0 +1,45 @@
+"""The MCP server: registers the dataxplan tools and runs over stdio.
+
+All tools are pure, read-only computations on the plan the agent supplies; the
+server never connects to a database. They are marked with annotations so a
+client can present and auto-run them safely.
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP, Image
+from mcp.types import ToolAnnotations
+
+from . import _tools
+
+mcp = FastMCP("dataxplan")
+
+
+def _annotations(title: str) -> ToolAnnotations:
+    return ToolAnnotations(
+        title=title,
+        readOnlyHint=True,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+
+
+mcp.tool(annotations=_annotations("Analyse an EXPLAIN plan"))(_tools.analyze_plan)
+mcp.tool(annotations=_annotations("Compare two plans (regression)"))(_tools.compare_plans)
+mcp.tool(annotations=_annotations("Annotated plan tree"))(_tools.plan_tree)
+mcp.tool(annotations=_annotations("Describe the inputs"))(_tools.describe_inputs)
+
+
+@mcp.tool(annotations=_annotations("Self-time chart (PNG)"))
+def plan_chart(plan: str) -> Image:
+    """Render the self-time-per-node chart for a plan as a PNG image."""
+    return Image(data=_tools.plan_png(plan), format="png")
+
+
+def main() -> None:
+    """Console-script entry point: run the server on stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

dataxplan_mcp-0.1.0/dataxplan_mcp.egg-info/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: dataxplan-mcp
+Version: 0.1.0
+Summary: MCP server for dataxplan: read PostgreSQL EXPLAIN plans for AI agents (bottlenecks, estimation errors, fixes, charts).
+Author: Atakan Arikan
+License: MIT
+Project-URL: Homepage, https://github.com/arikanatakan/dataxplan-mcp
+Project-URL: Repository, https://github.com/arikanatakan/dataxplan-mcp
+Project-URL: Issues, https://github.com/arikanatakan/dataxplan-mcp/issues
+Project-URL: Library, https://github.com/arikanatakan/dataxplan
+Keywords: mcp,model-context-protocol,ai-agents,postgresql,postgres,explain,query-plan,performance,query-optimization,database
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dataxplan[viz,yaml]>=0.1.3
+Requires-Dist: mcp>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+<!-- mcp-name: io.github.arikanatakan/dataxplan-mcp -->
+
+# dataxplan-mcp
+
+[![CI](https://github.com/arikanatakan/dataxplan-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/arikanatakan/dataxplan-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/dataxplan-mcp)](https://pypi.org/project/dataxplan-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+An MCP server that exposes [dataxplan](https://github.com/arikanatakan/dataxplan),
+the PostgreSQL EXPLAIN-plan analyzer for Python, as tools for AI agents: give it
+the output of `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` and it returns the
+bottlenecks, the estimation errors, documented findings with a suggested action
+and a source reference, a regression comparison, and a self-time chart.
+
+Agents asked why a query is slow tend to eyeball the plan and get it wrong: self
+time is per loop and inclusive of children, so the slow node is rarely the
+obvious one, and a row mis-estimate (the usual root cause) is buried in the
+output. Reading the plan belongs in a deterministic, versioned library that the
+agent calls, which leaves the agent to interpret the result and decide. The
+server never connects to a database: the agent runs EXPLAIN and passes the
+output, so nothing leaves its environment.
+
+![dataxplan-mcp architecture: an AI agent calls the server's analysis and chart tools, which route to the validated dataxplan core and return structured JSON or a PNG chart](assets/architecture.png)
+
+## Tools
+
+**Analysis tools** return dataxplan's payload: the metrics, the findings (each
+with a severity, a suggestion and a documented source reference) and a summary.
+
+| Tool | Purpose |
+| ---- | ------- |
+| `analyze_plan` | bottlenecks, estimation errors and findings from an EXPLAIN plan (JSON, text, YAML or XML) |
+| `compare_plans` | compare two plans for regression (timing, shape, estimates, findings) |
+| `plan_tree` | the plan as an annotated text tree (self time, rows, flags per node) |
+| `describe_inputs` | how to produce the plan, the accepted formats, the findings and the thresholds |
+
+**Chart tools** return a PNG image.
+
+| Tool | Purpose |
+| ---- | ------- |
+| `plan_chart` | self time per node, with the high-severity findings highlighted |
+
+All tools are read-only, and the server makes no database connection.
+
+## Installation
+
+Run it with [uv](https://docs.astral.sh/uv/) (no install needed):
+
+```
+uvx dataxplan-mcp
+```
+
+or install from PyPI:
+
+```
+pip install dataxplan-mcp
+```
+
+## Configuration
+
+Add it to your MCP client. For example:
+
+```json
+{
+  "mcpServers": {
+    "dataxplan": {
+      "command": "uvx",
+      "args": ["dataxplan-mcp"]
+    }
+  }
+}
+```
+
+If you installed with pip, use `"command": "dataxplan-mcp"` with no args.
+
+## Example
+
+```
+analyze_plan(plan="<EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) output>")
+  -> { "summary_metrics": { "execution_time_ms": 1240.0,
+                            "max_estimation_error": 20000, ... },
+       "findings": [ { "id": "seq_scan_hot", "severity": "high",
+                       "detail": "... 95% of execution time ...",
+                       "suggestion": "consider an index ...",
+                       "reference": "PostgreSQL: Using EXPLAIN; the Indexes chapter" } ],
+       "summary": "dataxplan - ...\n  execution time ..." }
+```
+
+The agent runs the EXPLAIN itself and pastes the output (any format) as `plan`.
+
+## Design
+
+The server is a thin, stateless wrapper. All of the analysis lives in the
+dataxplan library, which computes the metrics from the documented EXPLAIN fields
+and grounds each finding in the PostgreSQL manual (and Leis et al. 2015 for the
+estimation rules). The server adds the tool schema, read-only annotations and an
+input-schema helper so an agent can format the input and act on the result. The
+findings are documented heuristics, not guarantees, and the server connects to
+nothing.
+
+## Related
+
+- [dataxplan](https://github.com/arikanatakan/dataxplan): the library this server
+  wraps.
+
+## License
+
+MIT. Written and maintained by [Atakan Arikan](https://github.com/arikanatakan),
+MSc Student at Tsinghua University and Politecnico di Milano.

dataxplan_mcp-0.1.0/dataxplan_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+dataxplan_mcp/__init__.py
+dataxplan_mcp/_tools.py
+dataxplan_mcp/_version.py
+dataxplan_mcp/server.py
+dataxplan_mcp.egg-info/PKG-INFO
+dataxplan_mcp.egg-info/SOURCES.txt
+dataxplan_mcp.egg-info/dependency_links.txt
+dataxplan_mcp.egg-info/entry_points.txt
+dataxplan_mcp.egg-info/requires.txt
+dataxplan_mcp.egg-info/top_level.txt
+tests/test_server.py
+tests/test_tools.py

dataxplan_mcp-0.1.0/dataxplan_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dataxplan_mcp-0.1.0/dataxplan_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dataxplan-mcp = dataxplan_mcp.server:main

dataxplan_mcp-0.1.0/dataxplan_mcp.egg-info/requires.txt

@@ -0,0 +1,8 @@
+dataxplan[viz,yaml]>=0.1.3
+mcp>=1.0
+
+[dev]
+pytest>=7
+ruff
+mypy
+build

dataxplan_mcp-0.1.0/dataxplan_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+dataxplan_mcp

dataxplan_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dataxplan-mcp"
+version = "0.1.0"
+description = "MCP server for dataxplan: read PostgreSQL EXPLAIN plans for AI agents (bottlenecks, estimation errors, fixes, charts)."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Atakan Arikan" }]
+requires-python = ">=3.10"
+dependencies = ["dataxplan[viz,yaml]>=0.1.3", "mcp>=1.0"]
+keywords = [
+    "mcp", "model-context-protocol", "ai-agents", "postgresql", "postgres",
+    "explain", "query-plan", "performance", "query-optimization", "database",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+]
+
+[project.scripts]
+dataxplan-mcp = "dataxplan_mcp.server:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff", "mypy", "build"]
+
+[project.urls]
+Homepage = "https://github.com/arikanatakan/dataxplan-mcp"
+Repository = "https://github.com/arikanatakan/dataxplan-mcp"
+Issues = "https://github.com/arikanatakan/dataxplan-mcp/issues"
+Library = "https://github.com/arikanatakan/dataxplan"
+
+[tool.setuptools.packages.find]
+include = ["dataxplan_mcp*"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.mypy]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dataxplan_mcp-0.1.0/setup.cfg

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

dataxplan_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,18 @@
+def test_server_imports_and_wires():
+    from dataxplan_mcp import server
+
+    assert server.mcp is not None
+    assert callable(server.main)
+
+
+def test_all_tools_registered():
+    import asyncio
+
+    from dataxplan_mcp import server
+
+    names = {tool.name for tool in asyncio.run(server.mcp.list_tools())}
+    expected = {
+        "analyze_plan", "compare_plans", "plan_tree", "describe_inputs",
+        "plan_chart",
+    }
+    assert expected <= names

dataxplan_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,82 @@
+import json
+
+from dataxplan_mcp import _tools as t
+from dataxplan_mcp._tools import ContextInput, TableInfoInput
+
+PLAN = json.dumps([{
+    "Plan": {
+        "Node Type": "Seq Scan", "Relation Name": "orders",
+        "Startup Cost": 0.0, "Total Cost": 35811.0, "Plan Rows": 5,
+        "Plan Width": 244, "Actual Startup Time": 0.03,
+        "Actual Total Time": 900.0, "Actual Rows": 5, "Actual Loops": 1,
+        "Filter": "(status = 'X')", "Rows Removed by Filter": 10000000},
+    "Planning Time": 0.4, "Execution Time": 905.0}])
+
+FAST = json.dumps([{
+    "Plan": {
+        "Node Type": "Index Scan", "Relation Name": "orders",
+        "Index Name": "orders_pkey", "Plan Rows": 1, "Plan Width": 244,
+        "Total Cost": 8.3, "Actual Startup Time": 0.02, "Actual Total Time": 0.05,
+        "Actual Rows": 1, "Actual Loops": 1},
+    "Execution Time": 0.08}])
+
+
+def _ids(payload):
+    return {f["id"] for f in payload["findings"]}
+
+
+def test_analyze_plan():
+    r = t.analyze_plan(PLAN)
+    assert "summary" in r
+    ids = _ids(r)
+    assert "seq_scan_hot" in ids and "filter_discard" in ids
+    seq = next(f for f in r["findings"] if f["id"] == "seq_scan_hot")
+    assert seq["reference"] and seq["suggestion"]
+
+
+def test_analyze_plan_error_has_hint():
+    r = t.analyze_plan("not a plan at all")
+    assert "error" in r and "describe_inputs" in r["hint"]
+
+
+def test_analyze_with_context_sharpens():
+    ctx = ContextInput(tables={"orders": TableInfoInput(
+        row_count=10_000_000, indexed_columns=["id"])})
+    r = t.analyze_plan(PLAN, context=ctx)
+    seq = next(f for f in r["findings"] if f["id"] == "seq_scan_hot")
+    assert "10,000,000 rows" in seq["detail"]
+
+
+def test_analyze_accepts_text_format():
+    text = ("Seq Scan on orders  (cost=0.00..35811.00 rows=5 width=244) "
+            "(actual time=0.030..900.000 rows=5 loops=1)\n"
+            "  Rows Removed by Filter: 10000000\n"
+            "Execution Time: 905.000 ms\n")
+    assert "seq_scan_hot" in _ids(t.analyze_plan(text))
+
+
+def test_compare_plans():
+    r = t.compare_plans(PLAN, FAST)
+    assert r["verdict"] == "improved"
+
+
+def test_plan_tree():
+    tree = t.plan_tree(PLAN)
+    assert "Seq Scan on orders" in tree
+
+
+def test_describe_inputs():
+    d = t.describe_inputs()
+    assert d["findings"] and d["thresholds"] and d["accepted_formats"]
+    assert "min_time_ms" in d["thresholds"]
+
+
+def test_payload_is_json_serializable():
+    json.dumps(t.analyze_plan(PLAN))
+    json.dumps(t.compare_plans(PLAN, FAST))
+    json.dumps(t.describe_inputs())
+
+
+def test_plan_png():
+    png = t.plan_png(PLAN)
+    assert isinstance(png, bytes) and png[:4] == b"\x89PNG"