actionbook__actionbook/packages/mcp/README.md

Actionbook MCP Server

MCP server for Claude / Cursor and other AI Agents, providing two-step query capabilities:

• search_actions: Search for action manuals by keyword
• get_action_by_area_id: Get complete action content by area ID (plain text)

Installation & Running

Using Published Package

npx @actionbookdev/mcp --api-url http://localhost:3100

Using Local Source (Monorepo)

# Build
pnpm -C packages/mcp build

# Run
node packages/mcp/dist/cli.js --api-url http://localhost:3100

Configuration

Environment variables and CLI arguments (CLI arguments take precedence over environment variables):

Env Variable	CLI Argument	Description	Default
ACTIONBOOK_API_URL	--api-url <url>	API service URL	https://api.actionbook.dev
ACTIONBOOK_API_KEY	--api-key <key>	API Key	-
ACTIONBOOK_LOG_LEVEL	--log-level <level>	Log level (debug/info/warn/error)	info
ACTIONBOOK_TIMEOUT	--timeout <ms>	Request timeout (ms)	30000
ACTIONBOOK_RETRY_MAX	--retry-max <n>	Max retry attempts	3
ACTIONBOOK_RETRY_DELAY	--retry-delay <ms>	Retry delay (ms)	1000
ACTIONBOOK_TRANSPORT	--transport <type>	Transport mode (stdio/http)	stdio
ACTIONBOOK_HTTP_PORT	--http-port <port>	HTTP server port (http mode only)	3001
ACTIONBOOK_HTTP_HOST	--http-host <host>	HTTP server host (http mode only)	0.0.0.0
ACTIONBOOK_HTTP_CORS	--http-cors <origins>	CORS origins (comma-separated, http mode only)	*

Example Usage

Using environment variables:

export ACTIONBOOK_API_URL=http://localhost:3100
export ACTIONBOOK_API_KEY=your-key
export ACTIONBOOK_LOG_LEVEL=debug
npx @actionbookdev/mcp

Using CLI arguments:

npx @actionbookdev/mcp --api-url http://localhost:3100 --api-key your-key --log-level debug

Using HTTP transport:

# Environment variables
export ACTIONBOOK_TRANSPORT=http
export ACTIONBOOK_HTTP_PORT=3001
npx @actionbookdev/mcp

# CLI arguments (overrides environment)
npx @actionbookdev/mcp --transport http --http-port 3001 --http-host localhost

Development & Publishing

1. Local Development & Debugging

Claude Desktop Configuration (Recommended) Use absolute path to reference local build artifacts for stability:

{
  "mcpServers": {
    "actionbook-local": {
      "command": "node",
      "args": [
        "/absolute/path/to/actionbook/packages/mcp/dist/cli.js",
        "--api-url", "http://localhost:3000"
      ]
    }
  }
}

Tip: Use pnpm -C packages/mcp build --watch to enable watch mode. Changes will auto-compile (Claude restart required).

Using npm link

cd packages/mcp
npm link

# Test command
actionbook-mcp --help

2. Publish to NPM

cd packages/mcp

# 1. Login
npm login

# 2. Update version
npm version patch   # 0.1.0 → 0.1.1 (bug fix)
npm version minor   # 0.1.0 → 0.2.0 (new feature)
npm version major   # 0.1.0 → 1.0.0 (breaking change)

# 3. Build and publish (prepublishOnly auto-runs build)
npm publish

3. Install Published Version

# Global install (for CLI)
npm install -g @actionbookdev/mcp

# Or as project dependency
npm install @actionbookdev/mcp

# Or run directly with npx (no install needed)
npx @actionbookdev/mcp --api-url http://localhost:3100

If previously used npm link, clean up before installing:

npm rm -g @actionbookdev/mcp
npm cache clean --force
npm install -g @actionbookdev/mcp

4. Monorepo Internal Integration Testing

No publishing needed. Reference directly in other workspaces (e.g., packages/tools-ai-sdk):

1. Add dependency to package.json: "@actionbookdev/mcp": "workspace:*"
2. Write test scripts:

import { ActionbookMcpServer } from '@actionbookdev/mcp';
// ...use class for integration testing

MCP Client Configuration

Claude Desktop

{
  "mcpServers": {
    "actionbook": {
      "command": "npx",
      "args": ["-y", "@actionbookdev/mcp", "--api-url", "http://localhost:3100"],
      "env": {
        "ACTIONBOOK_API_KEY": "your-key"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "actionbook": {
      "command": "npx",
      "args": ["-y", "@actionbookdev/mcp", "--api-url", "http://localhost:3100"]
    }
  }
}

Test Coverage

• Core libs: config/protocol/errors/logger/formatter/schema/types/api-client
• Tools: search_actions / get_action_by_area_id
• Server: tool registration and invocation
• Integration: local HTTP stub to verify tool calls with actual API client