# askboard-mcp

`askboard-mcp` is a local MCP server for collecting structured human input from a browser. An AI client sends a form schema, Askboard opens a local web page, the user submits answers, and the MCP tool returns normalized JSON. It also keeps a searchable history dashboard so previous requests and edits stay reviewable.

The UI is rendered by the server itself, so it does not require MCP-UI support from Claude Code, Cursor, Cline, or other MCP clients.

## Features

- `ask_user`: open a browser form with single-choice, multi-choice, free-text, required fields, and custom write-in options.
- `open_dashboard`: open the local history dashboard.
- `get_updates`: read only sessions changed after a revision watermark.
- Searchable history: left-side session list, status filters, and right-side detail view.
- Editable history: update past answers from the dashboard; edits bump the session `rev`.
- Local-only storage: history is saved as JSON under `~/.askboard-mcp` by default.

## Install

```bash
npm install -g askboard-mcp
```

The package requires Node.js 20 or newer.

## MCP Client Configuration

After installing from npm:

```json
{
  "mcpServers": {
    "askboard": {
      "command": "askboard-mcp"
    }
  }
}
```

For local development from this repository:

```json
{
  "mcpServers": {
    "askboard": {
      "command": "node",
      "args": ["/absolute/path/to/askboard-mcp/dist/index.js"]
    }
  }
}
```

## Usage

Ask your AI client to use `ask_user` when it needs several decisions at once:

```json
{
  "title": "Confirm refactor scope",
  "intro": "Select the changes you want included.",
  "fields": [
    {
      "id": "scope",
      "label": "Scope",
      "type": "multi",
      "options": ["Split service layer", "Replace logger", "Add tests"],
      "allowCustom": true,
      "required": true
    },
    {
      "id": "priority",
      "label": "Priority",
      "type": "single",
      "options": ["Now", "Next iteration", "Defer"]
    },
    {
      "id": "notes",
      "label": "Notes",
      "type": "text",
      "placeholder": "Optional"
    }
  ]
}
```

The returned result includes the session id, status, revision, normalized answers, and dashboard URL.

## Tools

### `ask_user`

Shows an interactive browser form and waits for submission. Supported field types:

- `single`: one radio option, optionally with `allowCustom`.
- `multi`: checkbox options, optionally with `allowCustom`.
- `text`: free-form text area.

### `open_dashboard`

Opens `http://127.0.0.1:<port>/dashboard`. The dashboard has a left history rail, search, status filters, and a detail pane. Editing a pending record also answers the waiting tool call.

### `get_updates`

Reads history incrementally:

```json
{ "sinceRevision": 12 }
```

Response:

```json
{
  "revision": 15,
  "sinceRevision": 12,
  "count": 1,
  "changes": []
}
```

Pass the returned `revision` into the next `get_updates` call to avoid re-reading full history.

## Environment Variables

| Variable | Purpose | Default |
| --- | --- | --- |
| `ASKBOARD_PORT` | Starting port for the local web server. If busy, Askboard probes the next ports. | `7717` |
| `ASKBOARD_TIMEOUT_MS` | How long `ask_user` waits for a browser submission. | `600000` |
| `ASKBOARD_DATA_DIR` | Directory for `sessions.json`. | `~/.askboard-mcp` |

## Development

```bash
npm install
npm run build
npm test
npm run dev
```

`npm test` builds the TypeScript project, starts the stdio MCP server in an isolated temporary data directory, simulates a browser submission over HTTP, and verifies `ask_user`, `open_dashboard`, and `get_updates`.

## Release Automation

This repository includes:

- `.github/workflows/ci.yml`: build and test on Node.js 20 and 22.
- `.github/workflows/publish.yml`: validate and publish to npm with provenance on GitHub Release or manual dispatch.

For the first publish, the package name must be owned on npm. Because a package does not have npm package settings until it exists, use one of these paths:

- Run the `Publish` workflow with a GitHub Actions secret named `NPM_TOKEN` that contains an npm automation token.
- Or publish once from an authenticated local machine with `npm publish --access public`, then configure trusted publishing for later releases.

After the package exists, preferred npm setup is trusted publishing:

1. Publish the GitHub repository.
2. In npm, open the `askboard-mcp` package settings.
3. Add a trusted publisher for `qinsehm1128/askboard-mcp`.
4. Set workflow file to `.github/workflows/publish.yml`.
5. Set environment name to `npm`.
6. Create a GitHub Release or run the `Publish` workflow manually.

If trusted publishing is not available for the account, keep using the `NPM_TOKEN` secret.

## Storage and Privacy

Askboard stores history as local plaintext JSON. Do not collect secrets or sensitive production data unless the local machine and data directory are appropriate for that use.

## Project Structure

```text
src/
  index.ts          MCP server and tool registration
  webserver.ts      Local HTTP server, forms, dashboard, submission handlers
  storage.ts        JSON persistence and revision tracking
  browser.ts        Cross-platform browser opener
  types.ts          Shared data model
  lib/
    styles.ts       Shared CSS
    templates.ts    Form and dashboard HTML
```