Skip to main content
Glama
GuiaIA MCP Server

GuiaIA MCP Server


💡 What is GuiaIA?

Unlike conventional chatbots that simulate game awareness or scripts that blindly spam server commands, GuiaIA is an authentic, verifiable AI companion that connects to your Minecraft Java world as a co-player.

Every action GuiaIA performs—from walking and gathering wood to complex crafting trees, schematic construction, and Pokémon battles—is strictly anchored in:

  • Real Game Physics: Zero unearned success. The bot only acknowledges success when inventory deltas or block states are confirmed by the server.

  • Zero-Trust Cryptographic Security: Multi-party Ed25519 action grants, replay-proof monotonic sequences, and single-use nonces prevent command tampering and desynchronization.

  • Durable Write-Ahead Logging (WAL): Crash-resilient file persistence with fsync ensures that sudden disconnections never duplicate or lose resources.

  • Priority 0 Emergency Interruption: Instantaneous, single-key bot halts that bypass network nonces to stop all motion, block destruction, and combat immediately.


Related MCP server: OpenClaw MCP bridge

🚦 Verified Capabilities (V1.1.0)

GuiaIA follows a strict Honest Taxonomy standard. We distinguish simulated tests from real game execution:

Subsystem / Capability

Status

Taxonomic Classification

Verified Working Behavior

P0 Emergency Stop

🟢 Production

PASS REAL MINECRAFT

Aborts movement, pathfinding, digging, and combat in-flight within a single game tick.

Natural Language Companion

🟢 Production

PASS REAL MINECRAFT

Follows, guides, navigates terrain, and interacts via typed conversational commands.

Chained Tool Crafting DAG

🟢 Production

PASS REAL MINECRAFT

Decomposes complex recipes (e.g. wooden_pickaxe) into a 4-stage DAG, placing and using a 3x3 table.

Blueprint Construction Engine

🟢 Production

PASS REAL MINECRAFT

Places structures from NBT/JSON schematics with spatial collision checks, gravity validation, and WAL logging.

Cobblemon Radar

🟢 Production

PASS REAL MINECRAFT

Scans nearby Pokémon; species and levels strictly verified against server /data get entity NBT.

Cobblemon Poké Ball Capture

🟢 Production

PASS REAL MINECRAFT

Verifies ball consumption, confirms party insertion with Brigadier commands, and handles ACK loss fail-closed.

Cobblemon Wild Battles

🟢 Production

PASS REAL MINECRAFT

Exchanges turn-based moves, tracks health, and safely executes P0 halts via authoritative stopbattle.

PC Pokémon Storage

🟢 Production

PASS REAL MINECRAFT

Deposits and withdraws Pokémon between party and PC boxes, backed by persistent JSON storage.

Web Telemetry Dashboard

🟢 Production

PASS REAL SISTEMA

Real-time map, bot health, inventory viewer, P0 stop button, and PIN-authenticated REST API.

Triple Authority Security

🟢 Production

PASS REAL SISTEMA

Ed25519 session identity bridge, 10s single-use operator grants, and anti-rollback monotonic sequence witness.

Timing-Safe PIN Pairing

🟢 Production

PASS REAL SISTEMA

6-digit ephemeral PIN pairing with crypto.timingSafeEqual and permanent 3-attempt brute-force lockout.


⚡ Quickstart Guide

1. Prerequisites

  • Node.js: v20.x or v22.x LTS (Download)

  • Java: Adoptium Temurin OpenJDK 21 (Download)

  • Minecraft: Java Edition 1.21.1 (Vanilla or Fabric with Cobblemon 1.8.2)

2. Installation

Clone the repository and install the production dependencies:

git clone https://github.com/iagorobo24-hub/GuiaIA.git
cd GuiaIA/companion
npm ci

3. Launching the Interactive Companion

Start the interactive TUI console:

npm start
# or: node src/cli_v1.js

During boot, GuiaIA displays your 6-digit Web Dashboard PIN:

╔══════════════════════════════════════════════════════════════╗
║               GuiaIA Companion V1.1 Console                  ║
║  Web Dashboard: http://localhost:3000                        ║
║  Pairing PIN:   482910  (Valid for 5 minutes)                ║
╚══════════════════════════════════════════════════════════════╝

4. Accessing the Web Dashboard

Open your browser to http://localhost:3000:

  1. Enter the 6-digit PIN shown in your console.

  2. Monitor real-time bot position, health, inventory, and nearby entities.

  3. Access the Priority 0 Emergency Stop button directly from your browser.

5. Running the Autonomous Real Minecraft Lab

GuiaIA includes a self-contained test runner that automatically spins up an isolated, disposable Minecraft 1.21.1 + Fabric + Cobblemon 1.8.2 server and executes all 7 end-to-end missions:

# From repository root:
python scripts/qa_v1_1_real_minecraft_server.py

🧪 Comprehensive Verification & Test Suite

The entire codebase has been certified through an independent technical audit and adversarial stress testing:

Test Suite

Tests Run

Passed

Failed

Skipped

Status

Security & Cryptography (npm run test:security)

205

205

0

0

100% PASS

Product & Mechanics (npm run test:product)

166

165

0

1 (Teselia)

100% PASS

Product QA Matrix (v1_1_product_qa_matrix.test.js)

19

18

0

1 (Teselia)

100% PASS

Adversarial Security Stress (run_all_stress_tests.js)

32

32

0

0

100% PASS

Adversarial Mechanics Stress (run_all_challenger_tests.js)

50

50

0

0

100% PASS

In-Game E2E Missions (scripts/qa_v1_1_real_minecraft_server.py)

7

7

0

0

100% PASS

Total Consolidated

479

477

0

2

100% PASS

Note on Skips: The 2 skipped cases correspond exclusively to the multi-host physical witness test on Chromebook Teselia (PID 11085), strictly respecting our mandatory environment isolation rules.


🏛️ System Architecture

GuiaIA operates across four cleanly decoupled layers:

graph LR
    subgraph Client ["Operator Interfaces"]
        TUI["Interactive CLI"]
        WEB["Web Dashboard"]
    end

    subgraph Security ["Security Perimeter"]
        GATE["Ed25519 Gate & PIN Pairing"]
        WIT["Monotonic Witness"]
        P0["P0 Instant Halt"]
    end

    subgraph Engine ["Companion Engine"]
        DAG["Crafting DAG Planner"]
        BLD["Blueprint Builder"]
        COB["Cobblemon 1.8.2 Engine"]
        WAL["fsync WAL Journal"]
    end

    subgraph World ["Game Runtime"]
        BOT["Mineflayer Client"]
        MC["Fabric 1.21.1 Server"]
    end

    Client --> Security
    Security --> Engine
    Engine --> World

For detailed specifications, see System Architecture Specification.


📖 Documentation Index

  • System Architecture: Comprehensive component breakdown, security model, and network protocols.

  • Project Evolution & History: The full story from Python MCP prototypes to V1.1.0 certified production.

  • Master Audit Report: The official 17-finding audit log, adversarial stress benchmarks, and forensic certification.

  • User Manual: Step-by-step player guide, command reference, and troubleshooting.

  • Roadmap: Project milestones, completed phases, and upcoming features.

  • Contributing Guide: How to set up your dev environment, submit PRs, and run test suites.


🤝 Contributing

We welcome pull requests, bug reports, and suggestions! Please read our Contributing Guide to understand our coding standards, fail-closed design principles, and test taxonomy.


📄 License

GuiaIA is licensed under the MIT License.
Minecraft is a trademark of Mojang Synergies AB. Cobblemon is an open-source mod. GuiaIA is an independent open-source project and is not affiliated with Mojang or Microsoft.

Available Tools

5 tools
guia_diagnoseDiagnose performance without changing worldB
Read-only

Interpret existing telemetry and propose safe next steps; never applies fixes.

Inputs: no named parameters.

guia_performanceMinecraft performance snapshotB
Read-only

Read available metrics; absent data stays null (never guessed).

Inputs: no named parameters.

guia_plan_gatherPropose a bounded companion missionA
Read-only

Parse a Spanish request into an explicit non-executing plan. No gameplay actions.

Inputs: message (required).

guia_statusMinecraft world statusA
Read-only

Read sanitized status; does not reveal player names or change the world.

Inputs: no named parameters.

guia_world_observeRead bounded Fabric world observationA
Read-only

Read a recent, privacy-safe aggregate sample of one already-loaded chunk; no player identities or world changes.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 5 tools

    Disambiguation4/5

    The tools are mostly distinct: diagnose interprets telemetry, performance reads metrics, status reads sanitized status, world_observe reads chunk samples, and plan_gather parses requests into plans. However, diagnose, performance, status, and world_observe all overlap as read-only observability tools, which could cause some confusion for an agent deciding which read tool to use.

    Naming Consistency3/5

    All tools share the guia_ prefix, which provides some consistency. But the suffixes mix verbs, nouns, and verb_noun patterns (diagnose, performance, plan_gather, status, world_observe), making the naming convention only partially predictable.

    Tool Count5/5

    Five tools is well-scoped for a read-only diagnostics and planning server. Each tool appears to have a specific role, and the set is neither too thin nor too heavy.

    Completeness4/5

    For a read-only server that explicitly avoids applying fixes or modifying the world, the surface covers diagnosis, performance metrics, status reading, world observation, and planning. Minor gaps might exist around discovering available telemetry sources or detailed metric queries, but the core lifecycle is covered.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to query a live Factorio 2.0 world through bounded read-only operations covering spatial, inventory, resource, and diagnostic data over loopback RCON.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-compatible AI clients to inspect Godot project and editor state, observe opted-in running scenes, manage processes, and apply permission-scoped guarded edits. It starts read-only and exposes additional capabilities only through explicit command-line flags.
      Apache 2.0