McAgent Documentation

Before installing McAgent, verify that your server environment meets all mandatory prerequisites:

• Paper Server: Compatible with Minecraft api-version: 1.18 or higher.
• Java Runtime Environment: Java 17 minimum. Always use the Java release required by your active Paper build.
• LLM Provider: An AI model capable of reliable Tool/Function Calling (e.g. Claude 3.5 Sonnet, GPT-4o, DeepSeek-V3).
• Docker Runtime: Docker Desktop (Windows/macOS) or Docker Engine (Linux) is required only if the APR Programs feature is enabled.

1. Gracefully shutdown your Paper Minecraft server.
2. Copy the compiled McAgent.jar binary into your server's plugins/ folder.
3. Start the server once. McAgent will populate its workspace directory at plugins/McAgent/.
4. The workspace contains config.yml, the providers/ directory, APR resources, and internal storage stores.
5. Stop the server, edit config.yml with your credentials, and restart the server.

To avoid committing sensitive credentials into Git or configuration files, declare secrets in your operating system environment:

api-key: "ENV:OPENAI_API_KEY"
web:
  auth:
    token: "ENV:MCAGENT_WEB_TOKEN"

Example launching via PowerShell in the same session:

$env:OPENAI_API_KEY = "sk-your-actual-api-key"
$env:MCAGENT_WEB_TOKEN = "your-long-random-secure-web-token"
java -Xms2G -Xmx4G -jar paper.jar nogui

Below is the complete, non-truncated baseline configuration for production usage:

provider: local-gateway
model: ag/claude-sonnet-4-6
api-key: "ENV:OPENAI_API_KEY"
base-url: "http://127.0.0.1:20128/v1"

web:
  host: "127.0.0.1"
  port: 8765
  public-url: ""
  auth:
    enabled: true
    token: "ENV:MCAGENT_WEB_TOKEN"
    session-timeout-minutes: 480

agent:
  task-timeout-seconds: 7200
  max-steps: 160
  max-tool-calls: 320
  max-ask-user-per-task: 10
  max-compactions-per-task: 2147483647
  active-recovery-reserve-tokens: 8192
  verification-reserve-tokens: 4096
  tool-result-reserve-tokens: 4096

approval:
  timeout-seconds: 600
  file-read: ask
  file-write: ask
  minecraft-write: ask

filesystem:
  root: "."
  sensitive-name-patterns: []

memory:
  max-recent-turns: 80
  max-tasks: 500
  max-facts: 500
  consolidation:
    interval-hours: 24
    min-age-days: 7
    similarity-threshold: 0.8

embedding:
  model: "multilingual-e5-small"
  quantization: "int8"
  custom-model-path: ""
  custom-tokenizer-path: ""
  custom-dimension: 384

apr:
  enable: true
  runtime-image: "dungnice/mcagent-runtime@sha256:f202985b0607c9be395a5f691837a2d1301cbc393c4adede1aea4f1524c8decd"
  builder-image: "dungnice/mcagent-builder@sha256:3a0b3d0d4e1236a96bc3aec62b0c81ca08eb34db44829e78d0d874e2ed18b309"
  max-live-executions: 4
  total-cpu-percent: 200
  total-memory-mib: 2048
  total-pids: 96

self-healing:
  max-attempts: 3
  time-budget-seconds: 90
  circuit-breaker-threshold: 3

Inspect server console logs immediately after startup to ensure initialization was clean:

Model context budget: window=..., outputReserve=..., source=...
Enabled at http://127.0.0.1:8765

Log in to the Web UI using your secret token and send a read-only test prompt:

Inspect the server version, loaded plugins and current world state. Do not modify anything.

McAgent abstracts LLM protocols into declarative YAML profiles stored in plugins/McAgent/providers/<provider-id>.yml. The provider key in config.yml matches the filename without the .yml extension.

Built-in Provider IDs:

Full Provider Profile YAML Schema

Provider profiles are the complete declarative specification McAgent uses to communicate with an LLM API. Below is the full schema with every supported field.

Metadata & Connection block:

schema-version: 1
display-name: "Example Provider"
connection:
  transport: HTTP_JSON
  method: POST
  url: "https://api.example.com/v1/chat/completions"
  connect-timeout-ms: 10000
  request-timeout-ms: 180000
  stream-idle-timeout-ms: 60000
  follow-redirects: false
  headers:
    Content-Type: "application/json"
    Authorization: "Bearer ${config.api-key}"

Supported config bindings in profile YAML:

${config.model}
${config.api-key}
${config.base-url}
${config.streaming}
${config.provider-options.<key>}
${ENV:ENV_VAR_NAME}

Request mapping block:

request:
  body:
    model: "${config.model}"
    messages: "${mcagent.messages}"
    tools: "${mcagent.tools}"
    tool_choice: "${mcagent.tool-choice}"
    stream: true
    max_tokens: "${mcagent.output-limit}"

Response mapping block:

response:
  text-pointer: "/choices/0/message/content"
  finish-reason-pointer: "/choices/0/finish_reason"
  tool-calls:
    array-pointer: "/choices/0/message/tool_calls"
    id-pointer: "/id"
    name-pointer: "/function/name"
    arguments-pointer: "/function/arguments"
  usage:
    input-tokens-pointer: "/usage/prompt_tokens"
    output-tokens-pointer: "/usage/completion_tokens"
    total-tokens-pointer: "/usage/total_tokens"

Streaming (SSE) block:

stream:
  transport: SSE
  data-prefix: "data:"
  done-value: "[DONE]"
  text-delta-pointer: "/choices/0/delta/content"
  finish-reason-pointer: "/choices/0/finish_reason"
  tool-call-delta:
    array-pointer: "/choices/0/delta/tool_calls"
    index-pointer: "/index"
    id-pointer: "/id"
    name-pointer: "/function/name"
    arguments-delta-pointer: "/function/arguments"

Capabilities block:

capabilities:
  streaming: true
  tool-calling: true
  parallel-tool-calls: false
  vision-input: false
  usage-reporting: true
  system-message: true

Error mapping block:

errors:
  message-pointers:
    - "/error/message"
    - "/message"
  retryable-status:
    - 408
    - 429
    - 500
    - 502
    - 503
    - 504

Model Discovery & Context Defaults

Provider profiles can declare an optional model discovery block. McAgent uses it to auto-detect context window limits for the selected model:

model-discovery:
  enabled: true
  url: "https://openrouter.ai/api/v1/models"
  timeout-ms: 5000
  items-pointer: "/data"
  id-pointer: "/id"
  context-window-pointers:
    - "/context_length"
  max-output-pointers:
    - "/top_provider/max_completion_tokens"

context-defaults:
  context-window-tokens: 32768
  max-output-tokens: 4096

Context resolution priority order:

1. Query discovery endpoint; find item with exact id match against configured model.
2. Read first positive integer from context-window-pointers / max-output-pointers.
3. Fall back to context-defaults in provider profile.
4. Fall back to McAgent internal built-in conservative fallback.

APR allows the Agent to create and manage programs with their own source, manifest, build, logs, and lifecycle. APR does not turn the Web UI into a general IDE. It provides a controlled environment for Agent-authored programs serving specific tasks.

APR config block in config.yml:

apr:
  enable: true
  runtime-image: "dungnice/mcagent-runtime@sha256:f202985b0607c9be395a5f691837a2d1301cbc393c4adede1aea4f1524c8decd"
  builder-image: "dungnice/mcagent-builder@sha256:3a0b3d0d4e1236a96bc3aec62b0c81ca08eb34db44829e78d0d874e2ed18b309"
  max-live-executions: 4
  total-cpu-percent: 200
  total-memory-mib: 2048
  total-pids: 96

APR Docker prerequisites:

• Docker Engine must be running and the server process must have permission to call Docker CLI/daemon.
• Server must be able to reach Docker Hub to pull images on first launch.
• Images must be pinned by digest. Do not use :latest in config.

Manually verify Docker before starting the server:

docker info
docker pull dungnice/mcagent-runtime@sha256:f202985b0607c9be395a5f691837a2d1301cbc393c4adede1aea4f1524c8decd
docker pull dungnice/mcagent-builder@sha256:3a0b3d0d4e1236a96bc3aec62b0c81ca08eb34db44829e78d0d874e2ed18b309

Program Workspace Structure:

Portable user workspace (can be exported/imported):

programs/<definition-id>/
├── program.json
├── src/
│   ├── Main.java | main.py | index.js
│   ├── requirements.txt
│   ├── package.json
│   └── package-lock.json
├── resources/
└── modules/

Runtime-owned data (not exportable) lives in apr-runtime/runtime/programs/<id>/:

build/
state/
logs/
artifacts/
tmp/

Execution Type & Placement Matrix:

Standard Program Lifecycle:

1. CATALOG: Search for reusable existing programs.
2. INSPECT: Check metadata, revision, and build status.
3. CREATE: Create workspace if it does not exist.
4. WRITE: Write source files and program manifest.
5. DEFINE: Define the program entry point.
6. BUILD: Compile and install dependencies; verify output.
7. RUN / CALL / START: Execute based on type.
8. Verify result via independent state read-back when mutation occurred.
9. STOP for long-running programs; DESTROY only on explicit admin request.

Portable program.json Reference

The manifest is administrator-owned and portable. Runtime state, build output, approvals, and restoration authority are stored separately and are never granted by importing a manifest.

{
  "schemaVersion": 1,
  "id": "daily-report",
  "name": "Daily Report",
  "version": "1.0.0",
  "description": "Generate one bounded report.",
  "executionType": "ONE_SHOT",
  "kind": "PYTHON_PROGRAM",
  "buildProfile": "PYTHON_VALIDATE",
  "entrypoint": "main.py",
  "argv": ["python3", "main.py"],
  "workingDirectory": "lab",
  "placement": "DETACHED",
  "optionalApiDependencies": [],
  "modules": [],
  "callable": null,
  "operations": {}
}

Callable Java Contract and Verification

A callable is an explicit ONE_SHOT Java Program exposing public static String invoke(String). Input and output are validated with a closed JSON schema subset.

"callable": {
  "enabled": true,
  "name": "player_food_status",
  "description": "Read or set one online player's food level.",
  "inputSchema": {
    "type": "OBJECT",
    "properties": {
      "action": {"type": "STRING"},
      "target": {"type": "STRING"},
      "value": {"type": "INTEGER"}
    },
    "required": ["action", "target"],
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "OBJECT",
    "properties": {
      "ok": {"type": "BOOLEAN"},
      "result": {"type": "STRING"}
    },
    "required": ["ok", "result"],
    "additionalProperties": false
  },
  "entryClass": "apr.generated.food.Main",
  "entryContract": "public_static_string_invoke_string_v1"
}

Python Package Configuration (requirements.txt):

Declare exact versions in src/requirements.txt:

pymongo==4.13.2
requests==2.32.4

npm Package Configuration (package.json):

{
  "name": "my-program",
  "private": true,
  "dependencies": {
    "discord.js": "14.22.1",
    "mongodb": "6.17.0"
  }
}

Program Dependencies and Reusable APR Modules

These are separate mechanisms. A normal package belongs to one Program build. An APR Module is an immutable, qualified revision intentionally shared by multiple Programs.

APR Error Code Reference:

McAgent runs local ONNX embeddings for semantic memory ranking and skill search without sending vector data to a model provider. The embedding model is independent from the chat model selected under provider.

embedding:
  model: "multilingual-e5-small"
  quantization: "int8"
  custom-model-path: ""
  custom-tokenizer-path: ""
  custom-dimension: 384

Supported Built-in Models:

Data Storage Map:

Restart, Reload, and Backup Rules

• Restart after changing provider, model, environment secrets, embedding engine, APR enable state, or Docker image digests.
• Do not assume a Bukkit reload recreates Docker, HTTP, embedding, or provider runtime cleanly. Prefer a controlled server restart.
• Back up the entire plugins/McAgent/ directory while the server is stopped for a consistent recovery point.
• Redact api-key, Web token, provider headers, external credentials, and terminal secrets before sharing diagnostics.

Minimal Incident Capture

McAgent JAR SHA-256:
Java / Paper version:
Provider ID / model ID:
Context source from startup log:
APR enabled / Docker image digests:
Exact task text:
Final status and first error code:
Redacted server log / APR terminal excerpt: