# qq-agent

`qq-agent` is a zero-dependency CLI, MCP stdio server, and Agent Skill for a real, logged-in QQ account. It talks to a local **OneBot 11 HTTP endpoint**, normally provided by [NapCat](https://github.com/NapNeko/NapCatQQ), and keeps sending disabled by default.

> This package publishes only the NapCat/OneBot route. The macOS Computer Use skill is a separate project and should remain the default QQ route on macOS. Do not automatically enable this route on macOS unless the user explicitly requests NapCat/OneBot.

## What is included

| Component | Purpose |
|---|---|
| `bin/qq.mjs` | Single-file CLI using Node built-ins only (`fetch`, `node:sqlite`) |
| `mcp/server.mjs` | MCP stdio server; every tool delegates to the CLI |
| `skills/qq-live/SKILL.md` | Agent Skill for Codex, DeepSeek Harness, Claude Code, and other Agent runtimes |
| `mock/mock-onebot.mjs` | Local fake OneBot endpoint for tests without QQ |
| `test/smoke.sh` | 22 CLI assertions against the mock endpoint |
| `test/mcp-smoke.sh` | 5 MCP JSON-RPC assertions against the mock endpoint |

The CLI and MCP server have no npm runtime dependencies. Node.js 22 or newer is required because the local archive uses `node:sqlite`.

## Route boundaries

Use this project when:

- The user explicitly wants the NapCat/OneBot route.
- The host is Linux, WSL, Docker, or a macOS setup where the user explicitly chose NapCat.
- A local `qq` CLI is useful to an Agent, script, or MCP client.

Do not use this project:

- As an automatic macOS fallback when the separate `qq-desktop-messaging` Computer Use skill is available.
- With a public HTTP endpoint or without a token.
- For bulk messaging, moderation, account impersonation, or unattended writes.

## Prerequisites

1. NapCat is running and the QQ NT client is logged in.
2. NapCat has an enabled **HTTP Server** network configuration.
3. Keep the NapCat endpoint bound to localhost or another trusted network.
4. Node.js `>=22`.

This repository does not bundle NapCat, QQ, or a QQ client. Follow the NapCat project documentation for installation and upstream versions.

## Install

From a checkout:

```bash
npm install -g .
qq version
qq doctor
```

For local development:

```bash
npm link
qq version
npm test
```

## Configure

Environment variables are supported:

```bash
export QQ_ONEBOT_URL='http://127.0.0.1:3000'
export QQ_ONEBOT_TOKEN='replace-with-a-long-random-token'
qq doctor
```

Or create a protected config file from the example:

```bash
mkdir -p ~/.config/qq-agent
cp config.example.json ~/.config/qq-agent/config.json
chmod 600 ~/.config/qq-agent/config.json
```

The CLI checks `$QQ_CONFIG`, then `./.qq-agent.json`, then `~/.config/qq-agent/config.json`, then `~/.qq-agent.json`. Environment values override file values.

`allowSend` defaults to `false`. The send command fails until it is explicitly enabled, and a dry run is always available:

```bash
qq send --session group:123456 --text 'hello' --dry-run
```

## CLI

```bash
qq version
qq doctor
qq manifest
qq status
qq sessions --keyword 'team'
qq history --session group:123456 --limit 100 --format agent
qq context --session group:123456 --seq 9002 --window 10
qq forward --id 123456789
qq sync --session group:123456
qq search 'migration' --session group:123456
qq media --file pic_001.jpg --kind image
qq media --file voice.silk --kind record
qq files --session group:123456
qq files-url --session group:123456 --file-id f1
qq download --url 'https://example.invalid/file' --out ~/Downloads
qq send --session group:123456 --text 'hello' --dry-run
```

Session IDs are `group:123456` or `user:456`. The CLI emits one JSON envelope on stdout for `--format json|agent`; diagnostics go to stderr. Exit codes are `0` success, `2` usage/config error, `3` not found, `4` ambiguous, and `5` upstream/protocol error.

## Agent Skill

Install the Skill into an Agent skill directory:

```bash
mkdir -p ~/.codex/skills
cp -R skills/qq-live ~/.codex/skills/
```

For DeepSeek Harness, use the equivalent `~/.dsh/skills/` directory.

The Skill must not silently fall back to NapCat/OneBot on macOS. The user or runtime must explicitly select this route.

## MCP server

Codex `~/.codex/config.toml`:

```toml
[mcp_servers.qq]
type = "stdio"
command = "node"
args = ["<PATH_TO_QQ_AGENT>/mcp/server.mjs"]
env = { QQ_ONEBOT_URL = "http://127.0.0.1:3000", QQ_ONEBOT_TOKEN = "replace-with-token" }
```

The MCP server exposes read tools by default and delegates all execution to the CLI, so the CLI remains the single source of truth.

## Security

- Keep the OneBot endpoint on localhost or a trusted private network.
- Use a long random token. Never commit it.
- Keep `allowSend` disabled unless the user explicitly requests write access.
- Run `--dry-run` first for any send and verify the resolved session ID.
- Do not upload chat archives, media, tokens, or SQLite files to third-party services.
- This is not an official Tencent API and third-party protocol implementations can change.

See [SECURITY.md](SECURITY.md) for deployment details and vulnerability reporting.

## Testing

No QQ account is required for the test suite:

```bash
npm test
```

Or run either suite independently:

```bash
npm run test:cli
npm run test:mcp
```

The tests launch local mock OneBot endpoints on `127.0.0.1`, exercise read paths, verify the send gate, and check MCP JSON-RPC framing.

## Repository layout

```text
bin/qq.mjs              CLI implementation
mcp/server.mjs          MCP stdio adapter
skills/qq-live/         Agent Skill
mock/                   Mock OneBot HTTP endpoint
test/                   CLI and MCP smoke tests
config.example.json      Safe default configuration
```

## License

MIT. See [LICENSE](LICENSE).