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

npm install -g askboard-mcp

The package requires Node.js 20 or newer.

MCP Client Configuration

After installing from npm:

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

For local development from this repository:

{
  "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:

{
  "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:

{ "sinceRevision": 12 }

Response:

{
  "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

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

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