botdojo-tool

CLI for accessing BotDojo Resource Manager and MCP tools using a project Resource Token.

Installation

npm install -g @botdojo/tool-cli
# or
pnpm add -g @botdojo/tool-cli

This installs the global botdojo-tool command.

What It Does

• Registers a Resource Token and stores local credentials.
• Calls BotDojo MCP gateway tools.
• Refreshes access tokens automatically.
• Automatically re-runs registration when refresh requires re-approval.

Requirements

• Node.js 18+ (uses built-in fetch)
• A BotDojo Resource Token (bdres_...)
• BotDojo API URL via:
  • --api-url when running register, or
  • BOTDOJO_API_URL env var

Local Development

From repo root:

pnpm --filter ./packages/botdojo-tool-cli build
node packages/botdojo-tool-cli/lib/src/cli.js --help

From package directory:

pnpm build
node lib/src/cli.js --help

Global link for local development:

cd packages/botdojo-tool-cli
pnpm link --global
pnpm dev

Quick Start

1. Register once:

botdojo-tool register bdres_your_token_here --api-url https://api.botdojo.com

2. Use resource commands:

botdojo-tool list
botdojo-tool search "onboarding docs" --limit 5
botdojo-tool read "res://your/resource/uri" --expand

3. Call any MCP tool directly:

botdojo-tool e my_tool '{"q":"hello"}'
botdojo-tool e my_tool 'q=hello,limit=5'

Cheat Sheet

# Build locally
pnpm --filter ./packages/botdojo-tool-cli build

# Show help
node packages/botdojo-tool-cli/lib/src/cli.js --help

# First-time setup
botdojo-tool register bdres_your_token_here --api-url https://api.botdojo.com

# List exposed MCP tools
botdojo-tool tools

# List resources
botdojo-tool list

# Search resources
botdojo-tool search "onboarding docs"
botdojo-tool search "onboarding docs" --limit 5
botdojo-tool search "onboarding docs" --mime-type text/markdown

# Read a resource
botdojo-tool read "res://your/resource/uri"
botdojo-tool read "res://your/resource/uri" --metadata-only
botdojo-tool read "res://your/resource/uri" --expand
botdojo-tool read "res://your/resource/uri" --reason "Need docs for setup"

# Open / close an MCP or resource URI
botdojo-tool open "mcp://your/server/or/resource"
botdojo-tool close "res://your/resource/uri"

# Call any MCP tool directly
botdojo-tool e my_tool
botdojo-tool e my_tool '{"q":"hello","limit":3}'
botdojo-tool e my_tool 'q=hello,limit=3,enabled=true'

# Call a tool inside an MCP URI
botdojo-tool call "mcp://your/server" my_tool '{"q":"hello"}'
botdojo-tool call "mcp://your/server" my_tool 'q=hello,limit=3'
botdojo-tool call "mcp://your/server" my_tool '{}' --no-save-to-session

Command Reference

| Command | Purpose | Common options | | --- | --- | --- | | register <resource_token> | Exchange a bdres_... token for local credentials | --api-url <url> | | tools | List MCP tools exposed by the gateway | none | | e <tool_name> [parameters] | Call any MCP tool directly | JSON or key=value args | | read <uri> | Read a resource | --metadata-only, --expand, --reason | | open <mcp_uri> | Open a resource or MCP URI | --reason | | close <mcp_uri> | Close a resource URI | none | | search <query> | Search resources | --limit <n>, --mime-type <type> | | list | List resources | none | | call <mcp_uri> <tool_name> [parameters] | Call a tool inside a specific MCP URI | --no-save-to-session |

Parameters

e and call accept either:

• JSON object: {"key":"value","limit":3}
• key=value pairs: key=value,limit=3,enabled=true

Basic coercions for key=value format:

• true / false -> booleans
• null -> null
• numbers like 5 or 3.14 -> numbers

Stored State

• Credentials file: ~/.bd_resource/credentials.json
• Reused automatically after register
• Includes access token, refresh token, MCP session ID, and cached resource-manager tool names

Good To Know

• You only need --api-url during register; later commands reuse the stored API URL.
• Access tokens refresh automatically.
• If refresh requires re-approval, the CLI re-registers automatically and continues.
• If the saved MCP session is stale, the CLI reconnects and retries automatically.
• Resource commands like read and search auto-resolve the real MCP tool name even if the server uses a prefixed variant.

Common Failure Messages

• API URL is required... Run botdojo-tool register ... --api-url <url> or set BOTDOJO_API_URL.
• No local registration found... Run botdojo-tool register <resource_token> first.
• Unable to resolve Resource Manager tool... Run botdojo-tool tools and inspect the exposed tool names on that server.

Publishing

From the repo root:

pnpm publish:tool-cli

From the package directory:

pnpm build
pnpm publish --access public

Commands

register <resource_token>                    Register and store credentials
tools                                        List available MCP tools
e <tool_name> [parameters]                   Call a tool directly
read <uri>                                   Read resource content/metadata
open <mcp_uri>                               Open a resource or MCP URI
close <mcp_uri>                              Close a resource URI
search <query>                               Search resources
list                                         List resources
call <mcp_uri> <tool_name> [parameters]      Call tool inside an MCP URI

After register, the CLI reuses the stored API URL from local credentials. You do not need to pass --api-url on other commands.

Parameters Format

For e and call, parameters can be:

• JSON object: {"key":"value","limit":3}
• key=value pairs: key=value,limit=3,enabled=true

Credentials Storage

Credentials are stored at:

~/.bd_resource/credentials.json

The CLI writes this file with restrictive permissions (0600).

Notes

• If access tokens expire, the CLI refreshes automatically.
• If refresh fails due invalidation/re-approval requirements, the CLI re-registers and continues after approval.
• MCP session IDs and resolved tool mappings are persisted to reduce repeated negotiation.

Troubleshooting

• API URL is required...
  • Pass --api-url on register (or set BOTDOJO_API_URL) and register again.
• No local registration found...
  • Run botdojo-tool register <resource_token> first.
• Unable to resolve Resource Manager tool...
  • Run botdojo-tool tools and verify exposed tool names on the target server.