# tinyman-mcp

MCP (Model Context Protocol) server for the [Tinyman](https://tinyman.org) AMM DEX on Algorand.

Built on the [EmptyMCP](https://github.com/NautilusOSS/EmptyMCP) template for [UluOS](https://github.com/NautilusOSS/UluOS), following the same patterns as [HumbleSwapMCP](https://github.com/NautilusOSS/HumbleSwapMCP).

## Features

- **Pool discovery** — List top pools, get on-chain reserves, analytics
- **Token lookup** — Browse traded assets, resolve symbols to ASA IDs
- **Swap quotes** — Get expected output, rate, fee, price impact via Tinyman v2
- **Transaction building** — Unsigned swap, add-liquidity, remove-liquidity txns (base64-encoded for wallet signing)
- **Issue reporting** — File bugs or feature requests to GitHub Issues

## Tools

| Tool | Description |
|------|-------------|
| `get_pools` | List top Tinyman v2 liquidity pools |
| `get_pool` | Get on-chain pool info by asset pair |
| `get_pool_analytics` | Get analytics for a pool by address |
| `get_tokens` | List traded tokens with volume data |
| `get_asset_info` | Get on-chain ASA metadata |
| `get_asset_analytics` | Get Tinyman analytics for an asset |
| `get_asset_pools` | Get all pools containing an asset |
| `get_protocol_stats` | Get Tinyman protocol-wide statistics |
| `get_quote` | Get a swap quote (no txn built) |
| `swap_txn` | Build unsigned swap transactions |
| `add_liquidity_txn` | Build unsigned add-liquidity transactions |
| `remove_liquidity_txn` | Build unsigned remove-liquidity transactions |
| `report_issue` | Report a bug or feature request |

## Setup

```bash
npm install
```

## Usage

```bash
node index.js
```

## Adding to a Client

Add the following to your MCP client config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "tinyman-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/tinyman-mcp/index.js"]
    }
  }
}
```

## Architecture

```
index.js              Entry point — registers tools, starts stdio transport
data/
  contracts.json      Algorand mainnet/testnet node endpoints and app IDs
lib/
  client.js           Algod/Indexer client setup
  pools.js            Pool fetching via Tinyman SDK (poolUtils.v2)
  tokens.js           Token resolution and ASA lookup
  quote.js            Swap quotes via Tinyman SDK (Swap.v2)
  builders.js         Transaction builders (swap, add/remove liquidity)
  api.js              Tinyman analytics REST API calls
  utils.js            Unit conversion, JSON helpers, txn encoding
  reporting.js        GitHub issue submission
tools/
  pools.js            MCP pool tools
  tokens.js           MCP token tools
  trading.js          MCP trading tools (quotes, swaps, liquidity)
  reporting.js        MCP issue reporting tool
```

## Dependencies

- [@tinymanorg/tinyman-js-sdk](https://github.com/tinymanorg/tinyman-js-sdk) — Tinyman v2 AMM SDK
- [algosdk](https://github.com/algorand/js-algorand-sdk) — Algorand JavaScript SDK
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) — MCP server framework

## License

MIT