# 🕵️ TokenSpy MCP Server

**Give your AI agent access to pitfall intelligence and trading signals.**

[TokenSpy](https://www.tokenspy.ai) maintains a curated database of AI pitfalls (common mistakes, failure modes, and gotchas that cost teams real money) and trading signals (data-driven directional indicators). This MCP server lets AI agents like Claude, Cursor, and others query that data directly.

---

## Quick Start

```bash
npx tokenspy-mcp
```

That's it. Your AI agent can now search pitfalls and trading signals.

---

## Installation

### Option 1: npx (no install)

```bash
npx tokenspy-mcp
```

### Option 2: Global install

```bash
npm install -g tokenspy-mcp
tokenspy-mcp
```

---

## Configuration

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "tokenspy": {
      "command": "npx",
      "args": ["-y", "tokenspy-mcp"],
      "env": {
        "TOKENSPY_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Cursor

Add to your Cursor MCP settings (`.cursor/mcp.json` in your project or global config):

```json
{
  "mcpServers": {
    "tokenspy": {
      "command": "npx",
      "args": ["-y", "tokenspy-mcp"],
      "env": {
        "TOKENSPY_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Windsurf / Other MCP Clients

Any MCP-compatible client can use this server. Point it at:

```bash
npx tokenspy-mcp
```

The server communicates over **stdio** using the standard MCP protocol.

---

## Available Tools

### Pitfall Tools

| Tool | Description |
|------|-------------|
| `search_pitfalls` | Search the AI pitfall database by keyword and tags |
| `get_pitfall` | Get full details for a specific pitfall |
| `list_pitfalls` | List all available pitfalls |

### Signal Tools

| Tool | Description |
|------|-------------|
| `search_signals` | Search trading signals by keyword, ticker, or category |
| `get_signal` | Get full details for a specific signal |
| `list_signals` | List all available trading signals |

---

## Tool Examples

### Search for AI pitfalls

```
Agent: "Search for pitfalls related to RAG"

→ search_pitfalls({ query: "RAG" })

Returns:
[
  {
    "id": "pit_rag_001",
    "title": "RAG Retrieval Poisoning",
    "summary": "Attackers inject malicious content into...",
    "price": 4.99,
    "estimatedCostSaved": 50000,
    "tags": ["security", "rag", "retrieval"]
  }
]
```

### Get trading signal details

```
Agent: "What's the current BTC signal?"

→ search_signals({ ticker: "BTC" })

Returns:
[
  {
    "id": "sig_btc_momentum",
    "name": "BTC Momentum Oscillator",
    "ticker": "BTC",
    "direction": "bullish",
    "winRate": 0.72,
    "price": 9.99,
    "category": "crypto"
  }
]
```

---

## Free vs Paid Tier

| | Free | Paid |
|---|---|---|
| Search pitfalls | ✅ | ✅ |
| List pitfalls | ✅ | ✅ |
| Pitfall summaries | ✅ | ✅ |
| **Full pitfall content** | ❌ | ✅ |
| Search signals | ✅ | ✅ |
| List signals | ✅ | ✅ |
| Signal direction & win rate | ✅ | ✅ |
| **Full signal methodology** | ❌ | ✅ |

**Free tier** works without any API key — great for discovery and basic queries.

**Paid tier** requires a `TOKENSPY_API_KEY` environment variable. Get your API key at **[tokenspy.ai](https://www.tokenspy.ai)**.

---

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `TOKENSPY_API_KEY` | No | API key for full content access |

---

## API Documentation

Full API docs are available at [tokenspy.ai/docs](https://www.tokenspy.ai/docs).

---

## How It Works

This package implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) — an open standard for connecting AI agents to external tools and data sources. When you configure this server in Claude Desktop, Cursor, or any MCP client:

1. The client starts the `tokenspy-mcp` process
2. Communication happens over stdin/stdout using JSON-RPC
3. The AI agent can discover and call TokenSpy tools
4. All tools are **read-only** — no destructive operations, ever

---

## Development

```bash
git clone https://github.com/kypro-ai/tokenspy-mcp.git
cd tokenspy-mcp
npm install
npm run build
npm start
```

---

## License

MIT — see [LICENSE](./LICENSE).

---

Built with 🕵️ by [TokenSpy](https://www.tokenspy.ai)