# Installation Guide

This server is a local stdio MCP server. MCP clients launch it as a child process and communicate over stdin/stdout.

## Recommended User Install

After publishing this package to npm, users do not need to download the GitHub source code.

Run with `npx`:

```bash
npx -y @apidance/mcp
```

Or install globally:

```bash
npm install -g @apidance/mcp
apidance-mcp
```

Source checkout is mainly for development, auditing, or local modification.

## Bundled Codex Skill

The npm package includes a Codex Skill:

```text
skills/apidance-discover-twitter-team/
```

See the bundled Skill list:

```text
skills/README.md
skills/README.zh-CN.md
```

Run its bundled discovery service from the package root:

```bash
node skills/apidance-discover-twitter-team/scripts/run-discovery.mjs --help
```

The Skill service uses shared package code from:

```text
public-scripts/data-cleaning/twitter-normalize.mjs
src/server.js
```

If you copy the Skill folder into `~/.codex/skills`, keep `@apidance/mcp` installed and set `APIDANCE_MCP_PACKAGE_ROOT` to the package root before running its scripts.

## Run Directly From Source

```bash
node /Users/guang/ws/web3/apidance/apidance-mcp/bin/apidance-mcp.js
```

The server logs readiness to stderr and waits for MCP JSON-RPC messages on stdin.

## Codex

Use a Codex MCP server entry:

```toml
[mcp_servers.apidance_mcp]
command = "npx"
args = ["-y", "@apidance/mcp"]
startup_timeout_sec = 30

[mcp_servers.apidance_mcp.env]
APIDANCE_API_KEY = "your-apidance-api-key"
APIDANCE_AUTH_TOKEN = ""
APIDANCE_TIMEOUT_MS = "30000"
```

Notes:

- Put secrets in a user-level config, not in a committed repository file.
- Leave `APIDANCE_AUTH_TOKEN` empty unless you need account actions.
- Restart Codex after editing config.

For a local source checkout, use `node` and the local script path:

```toml
[mcp_servers.apidance_mcp]
command = "node"
args = ["/Users/guang/ws/web3/apidance/apidance-mcp/bin/apidance-mcp.js"]
startup_timeout_sec = 30
```

## Claude Code

Claude Code stdio command:

```bash
claude mcp add --transport stdio \
  --env APIDANCE_API_KEY=your-apidance-api-key \
  --env APIDANCE_AUTH_TOKEN= \
  apidance-mcp \
  -- npx -y @apidance/mcp
```

Project `.mcp.json` example:

```json
{
  "mcpServers": {
    "apidance-mcp": {
      "command": "npx",
      "args": ["-y", "@apidance/mcp"],
      "env": {
        "APIDANCE_API_KEY": "${APIDANCE_API_KEY}",
        "APIDANCE_AUTH_TOKEN": "${APIDANCE_AUTH_TOKEN:-}",
        "APIDANCE_TIMEOUT_MS": "30000"
      },
      "timeout": 600000
    }
  }
}
```

Claude Code supports environment expansion in `.mcp.json`, so team config can reference local shell variables without committing secrets.

## Claude Desktop

Add a server entry to the Claude Desktop MCP config:

```json
{
  "mcpServers": {
    "apidance-mcp": {
      "command": "npx",
      "args": ["-y", "@apidance/mcp"],
      "env": {
        "APIDANCE_API_KEY": "your-apidance-api-key",
        "APIDANCE_AUTH_TOKEN": ""
      }
    }
  }
}
```

Restart Claude Desktop after changing the config.

## Smoke Test

Check JavaScript syntax:

```bash
cd /Users/guang/ws/web3/apidance/apidance-mcp
npm run check
```

Initialize the MCP server manually:

```bash
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n' \
  | APIDANCE_API_KEY=test node ./bin/apidance-mcp.js
```

You should see an `initialize` response and a `tools/list` response.