Developer CLI

The onemcp-dev wrapper provides a fast development experience for working on OneMCP locally.

Overview

The developer CLI (onemcp-dev) is a Bash wrapper script designed for OneMCP contributors and developers who need to:

Iterate quickly on Java server changes
Debug the server locally
Test with custom Docker images
Access detailed logs and reports

Location: packages/dev-cli/onemcp-dev in the repository

Benefits

Fast Iteration

10-15 second rebuild for Java changes (vs minutes for Docker)
Incremental Maven builds
No Docker layer caching delays

Easy Debugging

Attach debuggers to local Java process
Set breakpoints in IDE
Step through code execution

Enhanced Logging

Persistent logs in ~/.onemcp/logs/
Execution reports with timestamps
Report paths displayed after each query

ACME Examples

Built-in example prompts for ACME Analytics handbook
Learn API capabilities quickly
Test common queries

Installation

The developer CLI is included in the repository. No separate installation needed.

Location: packages/dev-cli/onemcp-dev

Prerequisites:

OneMCP repository cloned locally
Go CLI built first (required):
```
cd packages/go-cli
go build -o onemcp
```
Java 21 installed
Maven installed
Docker Desktop (for regular usage)

Podman (optional, only for Docker mode):


brew install podman
podman machine init
podman machine start

Verify:


cd /path/to/onemcp
./packages/dev-cli/onemcp-dev --help

Usage

Fast Mode (Local Java)

Build and run Java server locally:


./packages/dev-cli/onemcp-dev chat

First run:

Builds Java project with Maven
Starts Java server locally
Connects Go CLI
~30 seconds initial build

Subsequent runs:

Only rebuilds changed files
~10-15 seconds
Full Java debugging available

When to use:

Iterating on Java server code
Debugging server issues
Testing API changes
Developing new features

Docker Mode


./packages/dev-cli/onemcp-dev chat --docker

Important: Docker mode requires Podman (not standard Docker)

Install Podman:


brew install podman
podman machine init
podman machine start

Behavior:

Cleans old dev images
Builds base image (if needed, ~2-3 min first time)
Builds product image with your JAR (~20s)
Transfers image from Podman to Docker/OrbStack
Removes redundant :latest tags
Runs with custom image

When to use:

Testing Docker-specific behavior
Validating production-like environment
Testing with custom base images
Pre-PR verification

Speed:

First time: ~2-3 minutes (builds base)
Subsequent: ~20 seconds (reuses base)

Clean Build

Force full rebuild (clears Maven cache):


./packages/dev-cli/onemcp-dev chat --clean

Use when:

Dependency changes
Build artifacts corrupted
Switching Java versions
Troubleshooting build issues

View Logs

Show development logs:


./packages/dev-cli/onemcp-dev logs           # Last 50 lines
./packages/dev-cli/onemcp-dev logs -n 100   # Last 100 lines
./packages/dev-cli/onemcp-dev logs -f       # Follow in real-time

Log location: ~/.onemcp/logs/dev-latest.log

Features

Persistent Logging

All logs and reports saved to ~/.onemcp/logs/:


~/.onemcp/logs/
├── dev-latest.log         # Latest session log
├── dev-TIMESTAMP.log      # Archived session logs
└── reports/               # Execution reports
    └── execution-TIMESTAMP.txt

Benefits:

Logs survive crashes and exits
Review past sessions
Share logs for debugging
Track execution history

Report Paths

After each query, see clickable execution report path:


You: Show total sales for 2024
Agent: {
  "message": "Total revenue for 2024 calculated successfully.",
  "total_revenue": 5640255.26
}
Report: /Users/you/.onemcp/logs/reports/execution-2025-12-03T10-30-45.txt

Click path to open report in editor and see:

Full execution plan
API calls made
Data transformations
Timing information

Note: Report paths only shown in dev mode currently.

ACME Example Prompts

When using the built-in ACME Analytics handbook, see helpful examples:


Mock Server Active - Try These Example Queries:

  > Show me electronics sales in California last quarter.
  > List top customers by revenue.
  > Compare revenue trends by region.
  > What are the top-selling products this month?
  > Show me sales data for New York vs Texas.

Type "help" anytime for more commands.

Automatic Cleanup

The dev CLI automatically cleans up:

OrientDB data directory (orientdb-data/) between runs
Docker images when switching modes
Stale processes

Result: Fresh environment each run, no state pollution.

Development Workflow

Typical Iteration Cycle

Make Java changes


# Edit server code
vim packages/server/src/main/java/...

Test changes (10-15s rebuild)
```
./packages/dev-cli/onemcp-dev chat
```
Review logs
```
./packages/dev-cli/onemcp-dev logs
```
Check report
- Click report path from chat output
- Review execution details
Iterate
- Make more changes
- Repeat from step 2

Debugging Java

Attach debugger:

Start dev CLI:
```
./packages/dev-cli/onemcp-dev chat
```
In IDE, attach to Java process:
- Host: localhost
- Port: 5005 (default JDWP port)
Set breakpoints in server code
Make queries in chat - hits breakpoints

IntelliJ IDEA:

Run → Attach to Process
Select Java process
Debug as usual

VS Code:

Add launch configuration:


{
  "type": "java",
  "request": "attach",
  "hostName": "localhost",
  "port": 5005
}

Start debugging

Testing Docker Builds

Before creating production Docker image, test locally:


# Build and test custom image
./packages/dev-cli/onemcp-dev chat --docker
 
# Verify image works correctly
# Test all functionality
 
# If issues found, fix and rebuild
./packages/dev-cli/onemcp-dev chat --docker --clean

Comparison to Production CLI

Feature	Production CLI	Developer CLI
Installation	Homebrew/Scoop	Repository only
Java	Docker image	Local or Docker
Rebuild time	–	10-15s (local)
Debugging	❌	✅
Report paths	❌	✅
Logs	Docker logs	`~/.onemcp/logs/`
ACME examples	✅	✅

Use production CLI for:

Normal usage
Writing handbooks
Testing APIs
Production deployments

Use developer CLI for:

OneMCP development
Server debugging
Java feature development
Testing local changes

Configuration

Environment Variables

ONEMCP_DEV_PORT - Server port (default: 8080)
ONEMCP_DEV_LOG_DIR - Log directory (default: ~/.onemcp/logs)

Example:


ONEMCP_DEV_PORT=9090 ./packages/dev-cli/onemcp-dev chat

Custom Handbooks

Use custom handbook with dev CLI:


# Set handbook directory
export ONEMCP_HANDBOOK_DIR=/path/to/custom/handbooks
 
# Run dev CLI
./packages/dev-cli/onemcp-dev chat

Troubleshooting

Java Build Fails


# Clean build to reset state
./packages/dev-cli/onemcp-dev chat --clean
 
# Or manually
cd packages/server
mvn clean package

Go CLI Not Found

Error:


Error: Go CLI not found at /path/to/go-cli/onemcp

Solution:


# Build the Go CLI first (required prerequisite)
cd packages/go-cli
go build -o onemcp
 
# Verify it exists
ls -la onemcp

Port Already in Use


# Find process using port 8080
lsof -i :8080
 
# Kill it
kill -9 <PID>
 
# Or use different port
ONEMCP_DEV_PORT=9090 ./packages/dev-cli/onemcp-dev chat

Docker Mode Fails


# Ensure Docker is running
docker ps
 
# Clean rebuild
./packages/dev-cli/onemcp-dev chat --docker --clean

Docker mode requires Podman:

If you see:


⚠️  Docker mode requires buildah or podman (not standard Docker)