<div align="center">

# TDM MCP Server

<img src="https://img.shields.io/badge/TDM-MCP_Server-ff69b4?style=for-the-badge&logo=server&logoColor=white" alt="TDM MCP Server" />

**Model Context Protocol Server for TDM**

[![npm](https://img.shields.io/badge/npm-@tdm/mcp--server-ff69b4?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@tdm/mcp-server)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-ff69b4?style=flat-square)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-ff69b4?style=flat-square)](./LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/ToDealMarket/mcp-server?style=flat-square&color=ff69b4)](https://github.com/ToDealMarket/mcp-server/stargazers)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-ff69b4?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)

*Session-state checks for AI agents*

[Documentation](https://todealmarket.com/docs) • [Quick Start](https://todealmarket.com/docs/quick-start) • [GitHub](https://github.com/todealmarket) • [X/Twitter](https://x.com/todealmarket)

</div>

---

## What is TDM MCP Server?

`@tdm/mcp-server` is a small MCP stdio server for TDM local session-state checks.

The public GitHub repo for `tdm-sdk` shows the open contract-facing SDK
surface: https://github.com/ToDealMarket/tdm-sdk

The current `tdm-sdk` npm beta used by the surrounding TDM docs remains
broader and includes the CLI/operator flows referenced here.

Inside the broader Integration Kit, this package is the reference MCP implementation.
It sits next to:

- thin CLI and signer wrappers
- copy-paste framework examples
- lightweight local integration recipes

```
████████╗ ██████╗  ███╗   ███╗
╚══██╔══╝ ██╔══██╗ ████╗ ████║
   ██║    ██║  ██║ ██╔████╔██║
   ██║    ██║  ██║ ██║╚██╔╝██║
   ██║    ██████╔╝ ██║ ╚═╝ ██║
   ╚═╝    ╚═════╝  ╚═╝     ╚═╝

TDM CLI [V0.0.2-BETA]
SDK + CLI + MCP
Mode: local-first | Docs: todealmarket.com/docs
```

---

## What it helps with

The tool helps an agent decide whether it should:

- continue
- ask the user to run `tdm connect`
- suggest `tdm fuel`
- suggest `tdm sweep`

Interactive seller commands in `tdm-sdk` can now auto-start that one-time
Live TDM setup when the live runtime is still missing. MCP still keeps the
explicit instruction path because an agent should ask the operator before
triggering wallet/browser setup on their behalf.

For human operator flows, `tdm connect` stores the primary wallet locally.
The current multi-wallet MVP also supports connecting one wallet per supported
network for local signing and network-specific payout setup. During connect,
TDM can attempt a safe default payout sync for the same network when that
network does not already have a saved payout wallet. It does not overwrite an
already saved payout wallet automatically, and
`tdm connect --no-sync-payout-wallet` keeps connect local-only.

If the account protects new payout destinations with TOTP step-up, the
operator should run:

```bash
tdm security totp enroll
tdm security totp verify --method-id <id> --code 123456
```

`tdm security totp enroll` opens a local setup page with a QR by default. Use
`--no-browser` if terminal-only setup is preferred.

It is intentionally local-first:

- reads local TDM credentials and runtime hints
- follows `TDM_CREDENTIALS_PATH` when explicitly set
- otherwise follows `TDM_VAULT` or the active vault marker from `~/.tdm/vaults/_active`
- does not depend on deprecated treasury balance routes
- can use `TDM_REMAINING_USDC` and `TDM_DUST_TOKENS_DETECTED` when the host wants to provide fresh snapshot hints

For operators using named vaults, MCP will read the active/default vault context instead of pretending there is only one global runtime forever.

The vault resolution order is explicit:

- `TDM_CREDENTIALS_PATH` when you pin one credentials file directly
- otherwise `TDM_VAULT`
- otherwise the active vault marker from `~/.tdm/vaults/_active`
- otherwise the legacy default `~/.tdm/credentials.json`

That means one MCP process reads one selected vault contour. It does not merge
agents, wallets, or sessions across multiple vaults.

If that active vault has its own optional runtime allowlist, agents in that
vault inherit the narrower destination policy. If no project or vault
allowlist is configured, MCP keeps the broader flexible runtime posture
instead of assuming deny-by-default.

If the operator wants reusable runtime contours, `tdm workspace use <name>`
can switch the active vault/storage combination before MCP starts. MCP still
reads local runtime state only; it does not own those runtime workspaces.

Local catalogs and published assets now live next to that same runtime layer in `tdm-sdk`:

- `tdm storage add`
- `tdm storage import-dir`
- `tdm storage sync`
- `tdm storage watch`
- `tdm storage publish`
- `tdm workspace`
- `tdm status`
- `tdm workspace status`

MCP itself does not host or upload those files. It can only help an agent or
operator decide when to suggest the surrounding CLI workflow.

## States

- `FUELED`
- `DEPLETED`
- `UNINITIALIZED`

Representative response fields:

- `state`
- `remaining_usdc`
- `wallet_linked`
- `dust_tokens_detected`
- `agent_instructions`
- `balance_source`

## Install

```bash
npm install @tdm/mcp-server
```

Global install:

```bash
npm install -g @tdm/mcp-server
```

If you already use `tdm-sdk`, the simplest path is:

```bash
tdm mcp
```

That SDK command writes a project `.mcp.json` pointing to the bundled MCP runtime.
The standalone `@tdm/mcp-server` package itself does not mutate your project config files.

## Run

```bash
tdm-mcp-server
```

Bundled SDK path:

```bash
tdm mcp serve
```

## Programmatic startup

```ts
import { startUltraThinRadarServer } from '@tdm/mcp-server';

await startUltraThinRadarServer();
```

## Example response

```json
{
  "state": "DEPLETED",
  "remaining_usdc": 0,
  "wallet_linked": true,
  "dust_tokens_detected": true,
  "agent_instructions": "Suggest tdm sweep.",
  "balance_source": "runtime_snapshot"
}
```

## Scope

This package is a decision helper for agent runtimes. It is not a wallet manager,
payout tool, or general execution framework.

If you need a live JavaScript gateway integration instead of local state
guidance, use `tdm-sdk` with `makePayable(...)`, `tdm-sdk/authorize`,
`tdm-sdk/checkout`, `tdm-sdk/session-tanks`, or `createGatewayClients(...)`.

If MCP suggests a recovery path such as `tdm sweep`, the current SDK routing
behavior behind that suggestion is:

- Solana Jupiter:
  - `https://api.jup.ag/swap/v1` when `JUPITER_API_KEY` is configured
  - `https://lite-api.jup.ag/swap/v1` as the compatibility fallback without a key
- Base Odos:
  - `https://api.odos.xyz` without `ODOS_API_KEY`
  - `https://enterprise-api.odos.xyz` with `ODOS_API_KEY`

The MCP server itself does not hold or manage those API keys; it only points
operators toward the surrounding `tdm-sdk` workflow.

If you need custom local signing for advanced third-party integrations, use the
experimental `tdm signer serve` mode from `tdm-sdk` instead of treating the MCP
server as a transaction executor.

Warning:

- advanced users only
- localhost-only signing surface
- blind signing risk exists
- TDM does not take responsibility for losses caused by compromised local scripts or unsafe third-party integrations in that mode

## License

MIT