npm package: @sweatent/askr
Description: MCP question-answering assistant with TUI management panel
Latest version: 1.0.0

<div align="center">

# askr

**MCP Q&A Assistant / MCP 问答助手**

Async Q&A capabilities for AI clients via MCP protocol, powered by any OpenAI-compatible API.

通过 MCP 协议为 AI 客户端提供异步问答能力，后端对接任意 OpenAI 兼容 API。

[English](./README.md) | [中文文档](./docs/README.zh-CN.md)

</div>

---

## Quick Start

```bash
# First time: launch the management panel to configure your provider
npx @sweatent/askr -m

# Start the MCP stdio server
npx @sweatent/askr
```

## Features

- **question** — Ask a single question with streaming support
- **agentq** — Ask multiple independent questions in parallel (configurable concurrency)
- **list** — View recent session statuses
- **check** — Retrieve session results with blocking wait, full content, and chain-of-thought support

## MCP Client Integration

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "askr": {
      "command": "npx",
      "args": ["askr"]
    }
  }
}
```

### Claude Code

Add via CLI or global config:

```bash
claude mcp add askr -- npx @sweatent/askr
```

Or manually edit `.claude/settings.json`:

```json
{
  "mcpServers": {
    "askr": {
      "command": "npx",
      "args": ["askr"]
    }
  }
}
```

### Cursor / Other MCP Clients

Configure a stdio-type MCP server with command `npx @sweatent/askr` per your client's documentation.

## Management Panel

```bash
npx @sweatent/askr -m
# or
npx @sweatent/askr --manage
```

Menu options:

1. **Manage Provider** — Configure Base URL, API Key, model (auto-fetch model list or manual input)
2. **Manage Questions** — View/close active sessions
3. **View Logs** — Browse session history with question, chain-of-thought, and answer (live refresh for running sessions)
4. **More Settings** — Max concurrency, timeout, fold characters, system prompt, language

Supports Chinese and English interfaces.

## Configuration

Config file is stored in the system data directory:

| Platform | Path |
|----------|------|
| Windows | `%AppData%/askr/config.json` |
| macOS | `~/Library/Application Support/askr/config.json` |
| Linux | `~/.config/askr/config.json` |

```json
{
  "language": "en",
  "provider": {
    "baseUrl": "https://api.example.com",
    "apiKey": "sk-xxx",
    "model": "gpt-4",
    "stream": true
  },
  "settings": {
    "maxConcurrent": 5,
    "timeout": 150,
    "foldChars": 1000,
    "systemPrompt": "You are a search assistant..."
  }
}
```

### Base URL

- Standard: `https://api.example.com` — automatically appends `/v1/chat/completions`
- Custom endpoint: `https://api.example.com/custom/path#` — trailing `#` means use as-is (strip the `#`)

## Tool Reference

### question

```json
{ "content": "What is REST and its core principles?" }
```

Ask a single question. Answers exceeding `foldChars` are truncated; use `check` for full content. Returns session ID on timeout.

### agentq

```json
{ "questions": ["What is Docker?", "What is Kubernetes?"] }
```

Parallel questions, up to `maxConcurrent`. Each question runs in isolated context, returning its own result or session ID.

### list

```json
{ "count": 5 }
```

Returns the most recent N session summaries (ID, timestamp, status, question preview).

### check

```json
{ "id": "a3f8k2", "showFull": true, "showThinking": true }
```

Retrieve session result. Blocks if the session is still running. Parameters:

- `showFull` — Return full answer without truncation
- `showThinking` — Include chain-of-thought content

## Highlights

- **Streaming** — SSE streaming with real-time session file updates
- **Auto fallback** — Automatically falls back to non-streaming if streaming fails
- **Chain-of-thought separation** — Detects `<think>` tags, `reasoning_content`, and `thinking` fields
- **Hot reload** — Config changes from the management panel take effect immediately, no restart needed
- **Session persistence** — All Q&A records saved locally with full history browsing

## Requirements

- Node.js >= 18

## Recommended Prompt

Add the following to your project's `CLAUDE.md` or other AI client system prompt for best results:

```markdown
## askr Usage Guidelines

You can use askr MCP tools to search and ask an external AI to assist with your tasks.

### When to Use

- **Pre-implementation research**: Before using unfamiliar or uncertain public APIs / library functions, query their signatures, parameters, usage, and caveats to avoid writing incorrect code from memory
- **Unfamiliar concepts**: Look up terms, protocols, or design patterns you don't fully understand
- **Latest information**: Query recently released versions, changelogs, news, or announcements that may not be covered in your training data
- **Troubleshooting**: When facing hard-to-solve errors or unexpected behavior, search for solutions including GitHub Issues, Stack Overflow discussions, etc.
- **Solution comparison**: When deciding between multiple technical approaches, query their trade-offs and community recommendations
- **Configuration & compatibility**: Look up platform-specific configurations or known compatibility issues for particular environments or versions

### Principles

1. Prefer your own knowledge first; use askr only when uncertain, potentially outdated, or needing external verification
2. Be specific in your questions, include necessary context (language, framework, version, etc.), avoid vague queries
3. Combine related sub-questions into one question; use agentq for unrelated parallel questions
4. Use check to retrieve timed-out results; re-ask if check times out twice
5. Use check(id, showFull: true) when you need the full untruncated answer
```

## License

MIT