axiomatic-mcp 0.0a3__tar.gz

axiomatic_mcp-0.0a3/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: axiomatic-mcp
+Version: 0.0a3
+Summary: Modular MCP servers for Axiomatic_AI
+Author-email: Axiomatic Team <developers@axiomatic.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/axiomatic/ax-mcp
+Project-URL: Issues, https://github.com/axiomatic/ax-mcp/issues
+Keywords: mcp,axiomatic,ai,fastmcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+
+# Axiomatic MCP Servers
+
+MCP (Model Context Protocol) servers that provide AI assistants with access to the Axiomatic_AI Platform - a suite of advanced tools for scientific computing, document processing, and photonic circuit design.
+
+## Available Servers
+
+### 📄 [Documents Server](./axiomatic_mcp/servers/documents/)
+
+Convert PDF documents to markdown with advanced OCR and layout understanding.
+
+### 🖌️ [Equations Server](./axiomatic_mcp/servers/equations/)
+
+Compose equation of your interest based on information in the scientific paper.
+
+### 🔬 [PIC Designer Server](./axiomatic_mcp/servers/pic/)
+
+Design photonic integrated circuits using natural language descriptions.
+
+### 📊 [Plots Server](./axiomatic_mcp/servers/plots/)
+
+Extract numerical data from plot images for analysis and reproduction.
+
+### 🖥️ [Code Execution Server](./axiomatic_mcp/servers/code_execution/)
+
+Execute Python code in a secure environment with support for selected libraries (`gdsfactory`, `z3`, `json`).  
+Useful for photonic design workflows, symbolic reasoning, and structured data manipulation.
+
+## Getting an API Key
+
+All Axiomatic MCP servers require an API key:
+
+1. Contact developers@axiomatic-ai.com to request access
+2. Add the API key to your MCP client configuration as `AXIOMATIC_API_KEY`
+
+## Installation
+
+Installation instructions can be found for each specific server in their README.
+
+### Setting up MCP Servers in AI Clients
+
+#### Claude Desktop
+
+1. Open Claude Desktop settings
+2. Navigate to Developer → Edit MCP config
+3. Add the server configuration(s) above
+4. Restart Claude Desktop
+
+#### Cursor
+
+1. Open Cursor settings (Cmd/Ctrl + ,)
+2. Search for "MCP"
+3. Add the server configuration(s) to the MCP settings
+4. Restart Cursor
+
+#### Other MCP Clients
+
+Refer to your client's documentation for MCP server configuration.
+
+## Development
+
+### Local Development Setup
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/axiomatic/ax-mcp.git
+cd ax-mcp
+```
+
+2. Install in development mode:
+
+```bash
+make install-dev
+```
+
+3. Configure your MCP client to use local Python modules:
+
+> See specific MCP server README for specific installation instructions.
+
+```json
+{
+  "axiomatic-documents": {
+    "command": "python",
+    "args": ["-m", "axiomatic_mcp.servers.documents"],
+    "env": {
+      "AXIOMATIC_API_KEY": "your-api-key-here"
+    }
+  }
+}
+```
+
+### Adding a New Server
+
+1. Create server directory:
+
+```bash
+mkdir axiomatic_mcp/servers/my_domain
+```
+
+2. Create `__init__.py`:
+
+```python
+from .server import MyDomainServer
+
+def main():
+    server = MyDomainServer()
+    server.run()
+```
+
+2. Create `__main__.py`:
+
+```python
+from . import main
+
+if __name__ == "__main__":
+    main()
+```
+
+3. Implement server in `server.py`:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="NAME",
+    instructions="""GIVE NICE INSTRUCTIONS""",
+    version="0.0.1",
+)
+
+@mcp.tool(
+    name="tool_name",
+    description="DESCRIPTION",
+    tags=["TAG"],
+)
+def my_tool():
+  pass
+
+# Add more tools as needed
+```
+
+4. Add entry point to `pyproject.toml`:
+
+```toml
+[project.scripts]
+axiomatic-mydomain = "axiomatic_mcp.servers.my_domain:main"
+```
+
+5. Update README.md with instructions on installing your server. You can generate the "Add to cursor" button [here](https://docs.cursor.com/en/tools/developers)
+
+6. Don't forget to link to your server's README.md in the main project README.md
+
+### Release Process
+
+#### Publishing a Release
+
+1. Create a new release branch
+1. Update version in `pyproject.toml`
+1. Commit and push changes
+1. Create a pull request titled "Release: YOUR FEATURE(s)". Include detailed description of what's included in the release.
+1. Create a GitHub release with tag `vX.Y.Z`
+1. GitHub Actions automatically publishes to PyPI
+
+The package is available at: https://pypi.org/project/axiomatic-mcp/
+
+## Contributing
+
+We welcome contributions! To add a new server or improve existing ones:
+
+1. Fork the repository
+2. Create a feature branch
+3. Implement your changes following the existing patterns
+4. Add documentation to your server directory
+5. Submit a pull request
+
+For detailed guidelines on adding new servers, see the [Development](#development) section.
+
+## Troubleshooting
+
+### Server not appearing in Cursor
+
+1. Restart Cursor after updating MCP settings
+2. Check the Output panel (View → Output → MCP) for errors
+3. Verify the command path is correct
+
+### Multiple servers overwhelming the LLM
+
+Install only the domain servers you need. Each server runs independently, so you can add/remove them as needed.
+
+### API connection errors
+
+1. Verify your API key is set correctly
+2. Check internet connection
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/axiomatic/ax-mcp/issues)
+- **Email**: developers@axiomatic-ai.com
+
+## Creating >>Add to Cursor<< button:
+
+Copy your MCP client configuration and paste it there:
+
+https://docs.cursor.com/en/tools/developers#generate-install-link

axiomatic_mcp-0.0a3/README.md

@@ -0,0 +1,203 @@
+# Axiomatic MCP Servers
+
+MCP (Model Context Protocol) servers that provide AI assistants with access to the Axiomatic_AI Platform - a suite of advanced tools for scientific computing, document processing, and photonic circuit design.
+
+## Available Servers
+
+### 📄 [Documents Server](./axiomatic_mcp/servers/documents/)
+
+Convert PDF documents to markdown with advanced OCR and layout understanding.
+
+### 🖌️ [Equations Server](./axiomatic_mcp/servers/equations/)
+
+Compose equation of your interest based on information in the scientific paper.
+
+### 🔬 [PIC Designer Server](./axiomatic_mcp/servers/pic/)
+
+Design photonic integrated circuits using natural language descriptions.
+
+### 📊 [Plots Server](./axiomatic_mcp/servers/plots/)
+
+Extract numerical data from plot images for analysis and reproduction.
+
+### 🖥️ [Code Execution Server](./axiomatic_mcp/servers/code_execution/)
+
+Execute Python code in a secure environment with support for selected libraries (`gdsfactory`, `z3`, `json`).  
+Useful for photonic design workflows, symbolic reasoning, and structured data manipulation.
+
+## Getting an API Key
+
+All Axiomatic MCP servers require an API key:
+
+1. Contact developers@axiomatic-ai.com to request access
+2. Add the API key to your MCP client configuration as `AXIOMATIC_API_KEY`
+
+## Installation
+
+Installation instructions can be found for each specific server in their README.
+
+### Setting up MCP Servers in AI Clients
+
+#### Claude Desktop
+
+1. Open Claude Desktop settings
+2. Navigate to Developer → Edit MCP config
+3. Add the server configuration(s) above
+4. Restart Claude Desktop
+
+#### Cursor
+
+1. Open Cursor settings (Cmd/Ctrl + ,)
+2. Search for "MCP"
+3. Add the server configuration(s) to the MCP settings
+4. Restart Cursor
+
+#### Other MCP Clients
+
+Refer to your client's documentation for MCP server configuration.
+
+## Development
+
+### Local Development Setup
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/axiomatic/ax-mcp.git
+cd ax-mcp
+```
+
+2. Install in development mode:
+
+```bash
+make install-dev
+```
+
+3. Configure your MCP client to use local Python modules:
+
+> See specific MCP server README for specific installation instructions.
+
+```json
+{
+  "axiomatic-documents": {
+    "command": "python",
+    "args": ["-m", "axiomatic_mcp.servers.documents"],
+    "env": {
+      "AXIOMATIC_API_KEY": "your-api-key-here"
+    }
+  }
+}
+```
+
+### Adding a New Server
+
+1. Create server directory:
+
+```bash
+mkdir axiomatic_mcp/servers/my_domain
+```
+
+2. Create `__init__.py`:
+
+```python
+from .server import MyDomainServer
+
+def main():
+    server = MyDomainServer()
+    server.run()
+```
+
+2. Create `__main__.py`:
+
+```python
+from . import main
+
+if __name__ == "__main__":
+    main()
+```
+
+3. Implement server in `server.py`:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="NAME",
+    instructions="""GIVE NICE INSTRUCTIONS""",
+    version="0.0.1",
+)
+
+@mcp.tool(
+    name="tool_name",
+    description="DESCRIPTION",
+    tags=["TAG"],
+)
+def my_tool():
+  pass
+
+# Add more tools as needed
+```
+
+4. Add entry point to `pyproject.toml`:
+
+```toml
+[project.scripts]
+axiomatic-mydomain = "axiomatic_mcp.servers.my_domain:main"
+```
+
+5. Update README.md with instructions on installing your server. You can generate the "Add to cursor" button [here](https://docs.cursor.com/en/tools/developers)
+
+6. Don't forget to link to your server's README.md in the main project README.md
+
+### Release Process
+
+#### Publishing a Release
+
+1. Create a new release branch
+1. Update version in `pyproject.toml`
+1. Commit and push changes
+1. Create a pull request titled "Release: YOUR FEATURE(s)". Include detailed description of what's included in the release.
+1. Create a GitHub release with tag `vX.Y.Z`
+1. GitHub Actions automatically publishes to PyPI
+
+The package is available at: https://pypi.org/project/axiomatic-mcp/
+
+## Contributing
+
+We welcome contributions! To add a new server or improve existing ones:
+
+1. Fork the repository
+2. Create a feature branch
+3. Implement your changes following the existing patterns
+4. Add documentation to your server directory
+5. Submit a pull request
+
+For detailed guidelines on adding new servers, see the [Development](#development) section.
+
+## Troubleshooting
+
+### Server not appearing in Cursor
+
+1. Restart Cursor after updating MCP settings
+2. Check the Output panel (View → Output → MCP) for errors
+3. Verify the command path is correct
+
+### Multiple servers overwhelming the LLM
+
+Install only the domain servers you need. Each server runs independently, so you can add/remove them as needed.
+
+### API connection errors
+
+1. Verify your API key is set correctly
+2. Check internet connection
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/axiomatic/ax-mcp/issues)
+- **Email**: developers@axiomatic-ai.com
+
+## Creating >>Add to Cursor<< button:
+
+Copy your MCP client configuration and paste it there:
+
+https://docs.cursor.com/en/tools/developers#generate-install-link

axiomatic_mcp-0.0a3/axiomatic_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Axiomatic MCP Servers - Modular MCP servers built with FastMCP."""
+
+__version__ = "1.0.0"

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/__init__.py

@@ -0,0 +1,9 @@
+"""Domain-specific MCP servers."""
+
+from .pic.server import mcp as pic_mcp
+
+servers = [
+    pic_mcp,
+]
+
+__all__ = ["pic_mcp"]

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/code_execution/__init__.py

@@ -0,0 +1,5 @@
+def main():
+    """Main entry point for the Code Execution server."""
+    from .server import mcp
+
+    mcp.run(transport="stdio")

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/code_execution/__main__.py

@@ -0,0 +1,4 @@
+from . import main
+
+if __name__ == "__main__":
+    main()

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/code_execution/server.py

@@ -0,0 +1,47 @@
+"""Code Execution MCP server."""
+
+from typing import Annotated
+
+from fastmcp import FastMCP
+from fastmcp.tools.tool import ToolResult
+from mcp.types import TextContent
+
+from ...shared import AxiomaticAPIClient
+
+mcp = FastMCP(
+    name="Axiomatic Code Execution",
+    instructions="""This server provides tools to execute Python code
+    securely in a sandboxed environment with limited supported libraries.""",
+    version="0.0.1",
+)
+
+
+@mcp.tool(
+    name="code_execution",
+    description="Execute Python code in a secure environment and return stdout or error trace",
+    tags=["python", "execute", "sandbox"],
+)
+async def execute_code(
+    code: Annotated[str, "The Python code to execute"],
+) -> ToolResult:
+    """Execute Python code securely in the Axiomatic environment."""
+
+    data = {"code": code}
+    response = AxiomaticAPIClient().post("/code-execution/python/execute", data=data)
+
+    output: str = response.get("output", "")
+    is_success: bool = response.get("is_success", False)
+    error_trace: str | None = response.get("error_trace")
+
+    text_output = f"Execution Result:\n\n{output}" if is_success else f"Execution Failed:\n\n{error_trace}"
+
+    return ToolResult(
+        content=[TextContent(type="text", text=text_output)],
+        structured_content={
+            "execution_result": {
+                "output": output,
+                "is_success": is_success,
+                "error_trace": error_trace,
+            }
+        },
+    )

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/documents/__init__.py

@@ -0,0 +1,5 @@
+def main():
+    """Main entry point for the Documents server."""
+    from .server import mcp
+
+    mcp.run(transport="stdio")

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/documents/__main__.py

@@ -0,0 +1,4 @@
+from . import main
+
+if __name__ == "__main__":
+    main()

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/documents/server.py

@@ -0,0 +1,41 @@
+"""Documents MCP server for filesystem document operations."""
+
+from pathlib import Path
+from typing import Annotated
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+from fastmcp.tools.tool import ToolResult
+from mcp.types import TextContent
+
+from ...shared.documents.pdf_to_markdown import pdf_to_markdown
+
+mcp = FastMCP(
+    name="Axiomatic Documents Server",
+    instructions="""This server provides tools to read, analyze, and process documents
+    from the filesystem using the Axiomatic_AI Platform.""",
+    version="0.0.1",
+)
+
+
+@mcp.tool(
+    name="document_to_markdown",
+    description="Convert a PDF document to markdown using Axiomatic's advanced OCR.",
+    tags=["document", "filesystem", "analyze"],
+)
+async def document_to_markdown(
+    file_path: Annotated[Path, "The absolute path to the PDF file to analyze"],
+) -> ToolResult:
+    try:
+        response = await pdf_to_markdown(file_path)
+        name = file_path.stem + ".md"
+        return ToolResult(
+            content=[TextContent(type="text", text=f"Generated markdown for: {name}\n\n```markdown\n{response.markdown}\n```")],
+            structured_content={
+                "suggestions": [
+                    {"type": "create_file", "path": name, "content": response.markdown, "description": f"Create {name} with the generated markdown"}
+                ]
+            },
+        )
+    except Exception as e:
+        raise ToolError(f"Failed to analyze PDF document: {e!s}") from e

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/equations/__init__.py

@@ -0,0 +1,5 @@
+def main():
+    """Main entry point for the equations server."""
+    from .server import mcp
+
+    mcp.run(transport="stdio")

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/equations/__main__.py

@@ -0,0 +1,4 @@
+from . import main
+
+if __name__ == "__main__":
+    main()

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/equations/server.py

@@ -0,0 +1,51 @@
+from pathlib import Path
+from typing import Annotated
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+from fastmcp.tools.tool import ToolResult
+from mcp.types import TextContent
+
+from axiomatic_mcp.shared.documents.pdf_to_markdown import pdf_to_markdown
+
+from ...shared import AxiomaticAPIClient
+
+mcp = FastMCP(
+    name="Axiomatic Equations Server",
+    instructions="""This server provides tools to compose and analyze equations.""",
+    version="0.0.1",
+)
+
+
+@mcp.tool(
+    name="compose_expression",
+    description=(
+        "Compose an expression of your interest given the information form the source documents "
+        "and equations residing there. Provide descrption of the expression you want to compose."
+    ),
+    tags=["equations", "compose"],
+)
+async def compose_expression(
+    file_path: Annotated[Path, "The absolute path to the PDF file to analyze"], task: Annotated[str, "The task to be done for expression composition"]
+) -> ToolResult:
+    """If you have scientific text with equations, but you dont see the equation you're
+    interested in then use this tool and simply say: >>Express the energy in terms of
+     valocity and position<<, or something like that. The tool will return the desired expression
+     together with sympy code that explain how it was derived."""
+    try:
+        response = await pdf_to_markdown(file_path)
+
+        input_body = {"source_doc": response.markdown, "task": task}
+
+        response = AxiomaticAPIClient().post("/document/expression/compose", data=input_body)
+
+        return ToolResult(
+            content=[
+                TextContent(type="text", text=f"Composed expression: {response.get('composed_expression')}"),
+                TextContent(type="text", text=f"Comments: {response.get('comments')}"),
+                TextContent(type="text", text=f"Composition code: {response.get('composition_code')}"),
+            ]
+        )
+
+    except Exception as e:
+        raise ToolError(f"Failed to analyze PDF document: {e!s}") from e

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/pic/__init__.py

@@ -0,0 +1,5 @@
+def main():
+    """Main entry point for the PIC server."""
+    from .server import mcp
+
+    mcp.run(transport="stdio")

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/pic/__main__.py

@@ -0,0 +1,4 @@
+from . import main
+
+if __name__ == "__main__":
+    main()

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/pic/server.py

@@ -0,0 +1,48 @@
+"""PIC (Photonic Integrated Circuit) domain MCP server."""
+
+from typing import Annotated
+
+from fastmcp import FastMCP
+from fastmcp.tools.tool import ToolResult
+from mcp.types import TextContent
+
+from ...shared import AxiomaticAPIClient
+
+mcp = FastMCP(
+    name="Axiomatic PIC Designer",
+    instructions="""This server provides tools to design, optimize,
+    and simulate photonic integrated circuits.""",
+    version="0.0.1",
+)
+
+
+@mcp.tool(
+    name="design_circuit",
+    description="Design a photonic integrated circuit and optionally create a Python file",
+    tags=["design", "gfsfactory"],
+)
+async def design(
+    query: Annotated[str, "The query to design the circuit"],
+    existing_code: Annotated[str | None, "Existing code to use as a reference to refine"] = None,
+) -> ToolResult:
+    """Design a photonic integrated circuit."""
+    data = {
+        "query": query,
+    }
+
+    if existing_code:
+        data["code"] = existing_code
+
+    response = AxiomaticAPIClient().post("/pic/circuit/refine", data=data)
+    code: str = response["code"]
+
+    file_name = "circuit.py"
+
+    return ToolResult(
+        content=[TextContent(type="text", text=f"Generated photonic circuit design for: {file_name}\n\n```python\n{code}\n```")],
+        structured_content={
+            "suggestions": [
+                {"type": "create_file", "path": file_name, "content": code, "description": f"Create {file_name} with the generated circuit design"}
+            ]
+        },
+    )

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/plots/__init__.py

@@ -0,0 +1,6 @@
+from .server import plots
+
+
+def main():
+    """Main entry point for the plots server."""
+    plots.run(transport="stdio")

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/plots/__main__.py

@@ -0,0 +1,4 @@
+from . import main
+
+if __name__ == "__main__":
+    main()

axiomatic_mcp-0.0a3/axiomatic_mcp/servers/plots/server.py

@@ -0,0 +1,127 @@
+"""Plot Parser MCP server"""
+
+import math
+import mimetypes
+import random
+from pathlib import Path
+from typing import Annotated
+
+from fastmcp import FastMCP
+from fastmcp.exceptions import ToolError
+from pydantic import BaseModel
+
+from ...shared import AxiomaticAPIClient
+
+
+class Point(BaseModel):
+    """Extracted point of a series from a plot"""
+
+    x_value: float
+    y_value: float
+
+
+class SeriesPoints(BaseModel):
+    """Extracted series from a plot"""
+
+    series_unique_id: int
+    points: list[Point]
+
+
+class SeriesPointsData(BaseModel):
+    """A list of points from each series in a plot"""
+
+    series_points: list[SeriesPoints]
+
+
+def process_plot_parser_output(response_json, max_points: int = 100, sig_figs: int = 5) -> SeriesPointsData:
+    extracted_series_list: list[SeriesPoints] = []
+
+    series_array = (response_json or {}).get("extracted_series") or []
+    for idx, extracted_series in enumerate(series_array):
+        all_extracted_points = extracted_series.get("points") or []
+        if not all_extracted_points:
+            continue
+
+        sample_size = min(max_points, len(all_extracted_points))
+        selected_points = random.sample(all_extracted_points, sample_size)
+
+        condensed_points_list: list[Point] = []
+        for point in selected_points:
+            x_raw = point.get("value_x")
+            y_raw = point.get("value_y")
+            if x_raw is None or y_raw is None:
+                continue
+            try:
+                x_num = float(x_raw)
+                y_num = float(y_raw)
+            except (TypeError, ValueError):
+                continue
+            if not math.isfinite(x_num) or not math.isfinite(y_num):
+                continue
+            x_val = float(format(x_num, f".{sig_figs}g"))
+            y_val = float(format(y_num, f".{sig_figs}g"))
+            condensed_points_list.append(Point(x_value=x_val, y_value=y_val))
+        if not condensed_points_list:
+            continue
+
+        series_id = extracted_series.get("id", idx)
+        try:
+            series_id = int(series_id)
+        except (TypeError, ValueError):
+            series_id = idx
+
+        series = SeriesPoints(series_unique_id=series_id, points=condensed_points_list)
+        extracted_series_list.append(series)
+    return SeriesPointsData(series_points=extracted_series_list)
+
+
+PLOTS_SERVER_INSTRUCTIONS = """This server hosts tools for extracting numerical data from plot images. 
+It can analyze line plots and scatter plots and convert visual data points into a structured numerical format."""
+
+plots = FastMCP(
+    name="Axiomatic plots tools server",
+    instructions=PLOTS_SERVER_INSTRUCTIONS,
+    version="0.0.1",
+)
+
+
+@plots.tool(
+    name="extract_numerical_series_points",
+    description="Analyzes images of line and scatter plots to extract precise numerical data points from all series in the plot",
+    tags={"plot", "filesystem", "analyze"},
+)
+async def extract_data_from_plot_image(
+    plot_path: Annotated[Path, "The absolute path to the image file of the plot to analyze. Supports only PNG for now"],
+    max_number_points_per_series: Annotated[
+        int,
+        "Maximum points returned per series. Uses random sampling if plot contains more points than limit",
+    ] = 100,
+) -> Annotated[SeriesPointsData, "Extracted plot data containing series and points from the plot image"]:
+    if not plot_path.is_file():
+        raise FileNotFoundError(f"Image not found or is not a regular file: {plot_path}")
+
+    supported_extensions = {".png"}
+    file_extension = plot_path.suffix.lower()
+    if file_extension not in supported_extensions:
+        raise ValueError(f"Unsupported image format: {file_extension}. Supported formats: {', '.join(supported_extensions)}")
+
+    mime_type, _ = mimetypes.guess_type(str(plot_path))
+    if not mime_type or not mime_type.startswith("image/"):
+        mime_type = "application/octet-stream"
+
+    with Path.open(plot_path, "rb") as f:
+        files = {"plot_img": (plot_path.name, f, mime_type)}
+        params = {"get_img_coords": True, "v2": True}
+
+        try:
+            response = AxiomaticAPIClient().post("/document/plot/points", files=files, params=params)
+        except Exception as e:
+            raise ToolError(f"Failed to analyze plot image: {e!s}") from e
+
+        if not isinstance(response, dict):
+            raise ToolError("Upstream service returned non-JSON response")
+
+        if "extracted_series" not in response:
+            raise ToolError("Upstream service returned unexpected response format")
+
+    return process_plot_parser_output(response, max_points=max_number_points_per_series)

axiomatic_mcp-0.0a3/axiomatic_mcp/shared/__init__.py

@@ -0,0 +1,7 @@
+"""Shared utilities for Axiomatic MCP servers."""
+
+from .api_client import AxiomaticAPIClient
+
+__all__ = [
+    "AxiomaticAPIClient",
+]

axiomatic_mcp-0.0a3/axiomatic_mcp/shared/api_client.py

@@ -0,0 +1,50 @@
+import os
+from typing import Any
+
+import httpx
+
+API_URL = "https://api.axiomatic-ai.com"
+TIMEOUT = 1000
+
+
+class AxiomaticAPIClient:
+    def __init__(self):
+        api_key = os.getenv("AXIOMATIC_API_KEY")
+        if not api_key:
+            raise ValueError("AXIOMATIC_API_KEY environment variable is not set")
+
+        self.client = httpx.Client(
+            base_url=API_URL,
+            timeout=TIMEOUT,
+            headers={
+                "X-API-Key": api_key,
+            },
+        )
+
+    def get(
+        self,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        response = self.client.get(endpoint, params=params)
+        response.raise_for_status()
+        return response.json()
+
+    def post(
+        self,
+        endpoint: str,
+        data: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        response = (
+            self.client.post(endpoint, files=files, data=data, params=params) if files else self.client.post(endpoint, json=data, params=params)
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.client.close()

axiomatic_mcp-0.0a3/axiomatic_mcp/shared/documents/pdf_to_markdown.py

@@ -0,0 +1,37 @@
+import asyncio
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from ...shared.api_client import AxiomaticAPIClient
+
+
+class ParseResponse(BaseModel):
+    markdown: str = Field(description="The extracted Markdown text, equations as latex, and images as base64 encoded strings.")
+    images: dict[str, str] = Field(default_factory=dict, description="Images as base64 encoded strings")
+    interline_equations: list[str] = Field(default_factory=list, description="Interline equations as latex")
+    inline_equations: list[str] = Field(
+        default_factory=list,
+        description="Inline equations as latex",
+    )
+
+
+async def pdf_to_markdown(file_path: Path) -> ParseResponse:
+    if not file_path.exists():
+        raise FileNotFoundError(f"Document not found: {file_path}")
+
+    if file_path.suffix.lower() != ".pdf":
+        raise ValueError("File must be a PDF")
+
+    file_content = await asyncio.to_thread(file_path.read_bytes)
+    files = {"file": (file_path.name, file_content, "application/pdf")}
+    data = {"method": "mistral", "ocr": False, "layout_model": "doclayout_yolo"}
+
+    response = await asyncio.to_thread(
+        AxiomaticAPIClient().post,
+        "/document/parse",
+        files=files,
+        data=data,
+    )
+
+    return ParseResponse(**response)

axiomatic_mcp-0.0a3/axiomatic_mcp.egg-info/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: axiomatic-mcp
+Version: 0.0a3
+Summary: Modular MCP servers for Axiomatic_AI
+Author-email: Axiomatic Team <developers@axiomatic.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/axiomatic/ax-mcp
+Project-URL: Issues, https://github.com/axiomatic/ax-mcp/issues
+Keywords: mcp,axiomatic,ai,fastmcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+
+# Axiomatic MCP Servers
+
+MCP (Model Context Protocol) servers that provide AI assistants with access to the Axiomatic_AI Platform - a suite of advanced tools for scientific computing, document processing, and photonic circuit design.
+
+## Available Servers
+
+### 📄 [Documents Server](./axiomatic_mcp/servers/documents/)
+
+Convert PDF documents to markdown with advanced OCR and layout understanding.
+
+### 🖌️ [Equations Server](./axiomatic_mcp/servers/equations/)
+
+Compose equation of your interest based on information in the scientific paper.
+
+### 🔬 [PIC Designer Server](./axiomatic_mcp/servers/pic/)
+
+Design photonic integrated circuits using natural language descriptions.
+
+### 📊 [Plots Server](./axiomatic_mcp/servers/plots/)
+
+Extract numerical data from plot images for analysis and reproduction.
+
+### 🖥️ [Code Execution Server](./axiomatic_mcp/servers/code_execution/)
+
+Execute Python code in a secure environment with support for selected libraries (`gdsfactory`, `z3`, `json`).  
+Useful for photonic design workflows, symbolic reasoning, and structured data manipulation.
+
+## Getting an API Key
+
+All Axiomatic MCP servers require an API key:
+
+1. Contact developers@axiomatic-ai.com to request access
+2. Add the API key to your MCP client configuration as `AXIOMATIC_API_KEY`
+
+## Installation
+
+Installation instructions can be found for each specific server in their README.
+
+### Setting up MCP Servers in AI Clients
+
+#### Claude Desktop
+
+1. Open Claude Desktop settings
+2. Navigate to Developer → Edit MCP config
+3. Add the server configuration(s) above
+4. Restart Claude Desktop
+
+#### Cursor
+
+1. Open Cursor settings (Cmd/Ctrl + ,)
+2. Search for "MCP"
+3. Add the server configuration(s) to the MCP settings
+4. Restart Cursor
+
+#### Other MCP Clients
+
+Refer to your client's documentation for MCP server configuration.
+
+## Development
+
+### Local Development Setup
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/axiomatic/ax-mcp.git
+cd ax-mcp
+```
+
+2. Install in development mode:
+
+```bash
+make install-dev
+```
+
+3. Configure your MCP client to use local Python modules:
+
+> See specific MCP server README for specific installation instructions.
+
+```json
+{
+  "axiomatic-documents": {
+    "command": "python",
+    "args": ["-m", "axiomatic_mcp.servers.documents"],
+    "env": {
+      "AXIOMATIC_API_KEY": "your-api-key-here"
+    }
+  }
+}
+```
+
+### Adding a New Server
+
+1. Create server directory:
+
+```bash
+mkdir axiomatic_mcp/servers/my_domain
+```
+
+2. Create `__init__.py`:
+
+```python
+from .server import MyDomainServer
+
+def main():
+    server = MyDomainServer()
+    server.run()
+```
+
+2. Create `__main__.py`:
+
+```python
+from . import main
+
+if __name__ == "__main__":
+    main()
+```
+
+3. Implement server in `server.py`:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="NAME",
+    instructions="""GIVE NICE INSTRUCTIONS""",
+    version="0.0.1",
+)
+
+@mcp.tool(
+    name="tool_name",
+    description="DESCRIPTION",
+    tags=["TAG"],
+)
+def my_tool():
+  pass
+
+# Add more tools as needed
+```
+
+4. Add entry point to `pyproject.toml`:
+
+```toml
+[project.scripts]
+axiomatic-mydomain = "axiomatic_mcp.servers.my_domain:main"
+```
+
+5. Update README.md with instructions on installing your server. You can generate the "Add to cursor" button [here](https://docs.cursor.com/en/tools/developers)
+
+6. Don't forget to link to your server's README.md in the main project README.md
+
+### Release Process
+
+#### Publishing a Release
+
+1. Create a new release branch
+1. Update version in `pyproject.toml`
+1. Commit and push changes
+1. Create a pull request titled "Release: YOUR FEATURE(s)". Include detailed description of what's included in the release.
+1. Create a GitHub release with tag `vX.Y.Z`
+1. GitHub Actions automatically publishes to PyPI
+
+The package is available at: https://pypi.org/project/axiomatic-mcp/
+
+## Contributing
+
+We welcome contributions! To add a new server or improve existing ones:
+
+1. Fork the repository
+2. Create a feature branch
+3. Implement your changes following the existing patterns
+4. Add documentation to your server directory
+5. Submit a pull request
+
+For detailed guidelines on adding new servers, see the [Development](#development) section.
+
+## Troubleshooting
+
+### Server not appearing in Cursor
+
+1. Restart Cursor after updating MCP settings
+2. Check the Output panel (View → Output → MCP) for errors
+3. Verify the command path is correct
+
+### Multiple servers overwhelming the LLM
+
+Install only the domain servers you need. Each server runs independently, so you can add/remove them as needed.
+
+### API connection errors
+
+1. Verify your API key is set correctly
+2. Check internet connection
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/axiomatic/ax-mcp/issues)
+- **Email**: developers@axiomatic-ai.com
+
+## Creating >>Add to Cursor<< button:
+
+Copy your MCP client configuration and paste it there:
+
+https://docs.cursor.com/en/tools/developers#generate-install-link

axiomatic_mcp-0.0a3/axiomatic_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,28 @@
+README.md
+pyproject.toml
+axiomatic_mcp/__init__.py
+axiomatic_mcp.egg-info/PKG-INFO
+axiomatic_mcp.egg-info/SOURCES.txt
+axiomatic_mcp.egg-info/dependency_links.txt
+axiomatic_mcp.egg-info/entry_points.txt
+axiomatic_mcp.egg-info/requires.txt
+axiomatic_mcp.egg-info/top_level.txt
+axiomatic_mcp/servers/__init__.py
+axiomatic_mcp/servers/code_execution/__init__.py
+axiomatic_mcp/servers/code_execution/__main__.py
+axiomatic_mcp/servers/code_execution/server.py
+axiomatic_mcp/servers/documents/__init__.py
+axiomatic_mcp/servers/documents/__main__.py
+axiomatic_mcp/servers/documents/server.py
+axiomatic_mcp/servers/equations/__init__.py
+axiomatic_mcp/servers/equations/__main__.py
+axiomatic_mcp/servers/equations/server.py
+axiomatic_mcp/servers/pic/__init__.py
+axiomatic_mcp/servers/pic/__main__.py
+axiomatic_mcp/servers/pic/server.py
+axiomatic_mcp/servers/plots/__init__.py
+axiomatic_mcp/servers/plots/__main__.py
+axiomatic_mcp/servers/plots/server.py
+axiomatic_mcp/shared/__init__.py
+axiomatic_mcp/shared/api_client.py
+axiomatic_mcp/shared/documents/pdf_to_markdown.py

axiomatic_mcp-0.0a3/axiomatic_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

axiomatic_mcp-0.0a3/axiomatic_mcp.egg-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+axiomatic-code-execution = axiomatic_mcp.servers.code_execution:main
+axiomatic-documents = axiomatic_mcp.servers.documents:main
+axiomatic-equations = axiomatic_mcp.servers.equations:main
+axiomatic-pic = axiomatic_mcp.servers.pic:main
+axiomatic-plots = axiomatic_mcp.servers.plots:main

axiomatic_mcp-0.0a3/axiomatic_mcp.egg-info/requires.txt

@@ -0,0 +1,10 @@
+fastmcp>=0.1.0
+pydantic>=2.0.0
+python-dotenv>=1.0.0
+httpx>=0.25.0
+
+[dev]
+pytest>=7.0.0
+black>=23.0.0
+ruff>=0.1.0
+mypy>=1.0.0

axiomatic_mcp-0.0a3/axiomatic_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+axiomatic_mcp

axiomatic_mcp-0.0a3/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "axiomatic-mcp"
+version = "0.0.alpha3"
+description = "Modular MCP servers for Axiomatic_AI"
+authors = [{name = "Axiomatic Team", email = "developers@axiomatic.ai"}]
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "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 :: Software Development :: Libraries :: Python Modules",
+]
+keywords = ["mcp", "axiomatic", "ai", "fastmcp"]
+urls = {Homepage = "https://github.com/axiomatic/ax-mcp", Issues = "https://github.com/axiomatic/ax-mcp/issues"}
+dependencies = [
+    "fastmcp>=0.1.0",
+    "pydantic>=2.0.0",
+    "python-dotenv>=1.0.0",
+    "httpx>=0.25.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[project.scripts]
+axiomatic-pic = "axiomatic_mcp.servers.pic:main"
+axiomatic-code-execution = "axiomatic_mcp.servers.code_execution:main"
+axiomatic-documents = "axiomatic_mcp.servers.documents:main"
+axiomatic-plots = "axiomatic_mcp.servers.plots:main"
+axiomatic-equations = "axiomatic_mcp.servers.equations:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["axiomatic_mcp*"]
+
+[tool.black]
+line-length = 150
+target-version = ["py310", "py311", "py312"]
+
+[tool.ruff]
+line-length = 150
+target-version = "py310"
+select = ["E", "F", "I", "N", "UP", "B", "C4", "PTH", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true

axiomatic_mcp-0.0a3/setup.cfg

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