Metadata-Version: 2.4
Name: yade-mcp
Version: 0.3.0
Summary: MCP server for YADE open-source discrete element method simulation
Project-URL: Homepage, https://github.com/yusong652/yade-mcp
Project-URL: Repository, https://github.com/yusong652/yade-mcp
Project-URL: Issues, https://github.com/yusong652/yade-mcp/issues
Project-URL: Discussions, https://github.com/yusong652/yade-mcp/discussions
Project-URL: Changelog, https://github.com/yusong652/yade-mcp/releases
Author-email: Yusong Han <yusong.han.652@gmail.com>, Nagisa Toyoura <nagisa.toyoura@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,anthropic,claude,dem,discrete-element,geomechanics,granular,llm,mcp,mcp-server,model-context-protocol,particle-simulation,scientific-computing,simulation,yade
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.14.0
Requires-Dist: pydantic>=2.12.0
Requires-Dist: websockets>=15.0.1
Description-Content-Type: text/markdown

# yade-mcp

<!-- mcp-name: io.github.yusong652/yade-mcp -->

<p align="center">
  <img src="https://raw.githubusercontent.com/yusong652/yade-mcp/assets/assets/header.gif" alt="yade-mcp header" width="720">
</p>

[English](https://github.com/yusong652/yade-mcp/blob/master/README.md) | [简体中文](https://github.com/yusong652/yade-mcp/blob/master/README.zh-CN.md)

[![PyPI](https://img.shields.io/pypi/v/yade-mcp)](https://pypi.org/project/yade-mcp/)
[![Downloads](https://static.pepy.tech/badge/yade-mcp)](https://pepy.tech/project/yade-mcp)
[![GitHub stars](https://img.shields.io/github/stars/yusong652/yade-mcp)](https://github.com/yusong652/yade-mcp/stargazers)
[![Glama](https://glama.ai/mcp/servers/yusong652/yade-mcp/badges/score.svg)](https://glama.ai/mcp/servers/yusong652/yade-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)

`O.engines += [LLM()]  # yet another engine.`

**yade-mcp** connects AI agents to [YADE](https://yade-dem.org/) — the open-source discrete element method engine — through the [Model Context Protocol](https://modelcontextprotocol.io/). Browse API docs, run simulations, and execute code, all through natural conversation.

![yade-mcp demo](https://raw.githubusercontent.com/yusong652/yade-mcp/assets/assets/demo.gif)

## Tools (7)

**2 documentation tools** — browse and search the YADE Python API with BM25 keyword search. No bridge required.

**5 execution tools** — synchronous REPL, async task submission, progress monitoring, interruption, and task history. Requires bridge.

## Quick Start

### Prerequisites

- **[YADE](https://yade-dem.org/doc/installation.html)** installed
- **[uv](https://docs.astral.sh/uv/getting-started/installation/)** installed (for `uvx`)

### Agentic Setup (Recommended)

Copy this to your AI agent and let it self-configure:

```text
Fetch and follow this bootstrap guide end-to-end:
https://raw.githubusercontent.com/yusong652/yade-mcp/master/docs/agentic/yade-mcp-bootstrap.md
```

### Manual Setup

**1. Register the MCP server** in your client config:

```json
{
  "mcpServers": {
    "yade-mcp": {
      "command": "uvx",
      "args": ["yade-mcp"]
    }
  }
}
```

**2. Start the bridge inside YADE:**

```bash
pip install yade-mcp-bridge
```

Then in a YADE Python console:

```python
import yade_mcp_bridge
yade_mcp_bridge.start()
```

### Verify

Restart your AI agent (Claude Code, Codex CLI, Gemini CLI, etc.) and ask it to call `yade_execute_code` to verify the connection.

## Features

- **API documentation & search** — browse and search the full YADE Python API with ranked results, real types, and defaults
- **Live code execution** — run code in the YADE process and get results back instantly, or submit long-running simulations with progress monitoring and interruption
- **User intent awareness** — agents automatically see what the user is doing in the YADE console, enabling contextual assistance without explicit instructions
- **Multi-client compatible** — works with Claude Code, Codex CLI, Gemini CLI, OpenCode, and other MCP clients

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## License

MIT — see [LICENSE](LICENSE).
