Skip to main content
Glama
iagorobo24-hub

GuiaIA MCP Server

GuiaIA 🧭

Your AI companion and world-engineering toolkit for Minecraft Java

Early developer preview — v0.1.0. GuiaIA is being developed as a Minecraft companion that can help you play, understand, build and improve your world. The public repository currently contains a small working foundation: a read-only local MCP gateway, a live Minecraft Java RCON status adapter, bounded mission proposals, an isolated performance snapshot analyzer and independent safety guards.

The player-like companion, vision, in-world construction and autonomous coding agents are roadmap features, not capabilities in this release. We prefer evidence over impressive-looking demos.

Why GuiaIA?

  • Companion (planned): follow players, gather materials, explore, remember adventures and help build.

  • World Observer (partially implemented): provide trusted observations to an agent, not imaginary world knowledge.

  • Developer Agent (prototype): investigate performance and propose safe tests and repairs in isolated QA environments.

The initial home for development is Minecraft Java 1.21.1 + Fabric, but the Python gateway is version-neutral and can read basic vanilla Minecraft RCON status. No server plugin or Fabric mod is installed by this repository.

Related MCP server: OpenClaw MCP bridge

Try it today (no Minecraft server required)

Requires Python 3.11+. The core has no runtime dependencies.

git clone https://github.com/iagorobo24-hub/GuiaIA.git
cd GuiaIA
PYTHONPATH=src python3 -m guiaia.mcp --snapshot examples/synthetic_world.json

This starts a stdio MCP server, designed for an MCP-compatible local AI client. It does not start an HTTP server, create a bot player or call any paid model.

For a local MCP client, configure its program to python3 and arguments to -m guiaia.mcp --snapshot /absolute/path/to/examples/synthetic_world.json with environment variable PYTHONPATH=/absolute/path/to/GuiaIA/src. Detailed examples are in MCP usage.

Once connected, you can ask an agent to use these four tools:

MCP tool

Working behavior

guia_status

Sanitized player count and game tick information

guia_performance

Read a trusted metric snapshot or explicitly report unavailable metrics

guia_diagnose

Propose a performance investigation without mutating anything

guia_plan_gather

Validate a bounded Spanish gather request; only propose, never execute

Connect to a running Minecraft Java server (operator only)

Minecraft RCON must already be enabled, reachable only on loopback and secured with an existing password stored in a local file. Do not expose RCON to the internet.

PYTHONPATH=src python3 -m guiaia.mcp --rcon-password-file /absolute/private/path/rcon.secret --rcon-port 25575

Only list and time query gametime are allowed through the adapter, and the output omits usernames. Performance metrics and the nearby world view are not available from this RCON-only adapter. Do not enter RCON passwords directly into an AI chat. Do not install experimental plugins into an active multiplayer server.

Development

PYTHONPATH=src python3 -m unittest discover -s tests -v
python3 -m compileall -q src tests

CI additionally installs and tests the package on Python 3.11, 3.12 and 3.13. Current test results are in milestones.

Architecture and roadmap

The planned sequence is observe → plan → policy/approval → execute in QA → verify → promote with authorization.

See architecture, roadmap, security, publication safeguards and open-source research.

Contribute

Suggestions, bug reports, tested integrations and discussions are welcome. Start with CONTRIBUTING.md. The project is MIT-licensed (see LICENSE) and makes no claim of affiliation with Mojang, Microsoft or the Cobblemon team.

Available Tools

4 tools
guia_diagnoseDiagnose performance without changing worldB
Read-only

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

NameRequiredDescriptionDefault

No parameters

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, and the description reinforces this with 'never applies fixes' and adds that it proposes next steps. That is useful confirmation, but it adds little beyond the annotation and says nothing about what the output looks like or how it is scoped.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded clause with the read-only guarantee as a semicolon qualifier — no waste. It is arguably too terse given the missing return-value context, but nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-param, read-only tool with no output schema, the description should at least hint at what comes back (a diagnosis, recommendations, next steps) and how it relates to guia_performance. The safety profile is covered, but the shape of the result is not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters and the schema is fully closed (additionalProperties: false), so there is nothing to document beyond what the schema already conveys; baseline 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a verb (interpret) and object (existing telemetry) plus the safety stance (never applies fixes), but 'diagnose' is only loosely specified — it does not say what a diagnosis consists of or how it differs from the sibling guia_performance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Interpret existing telemetry' hints that telemetry must already exist, but there is no explicit when-to-use, no when-not-to-use, and no reference to guia_performance, guia_status, or guia_plan_gather as alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

guia_performanceMinecraft performance snapshotB
Read-only

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

NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotation already declares readOnlyHint=true, so the description does not need to explain safety. It adds useful behavioral context by stating that absent data stays null and is never guessed, but it does not explain what metrics are returned or how the snapshot is structured.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no wasted words. It communicates the core action and the null-handling behavior efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read tool without an output schema, the description should clarify what metrics are available. It covers the null behavior but leaves the return content underspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4. No parameter semantics are needed beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a read action on metrics, but 'available metrics' is vague and does not explicitly say performance or Minecraft. It does not distinguish itself from siblings like guia_status or guia_diagnose, leaving the agent to infer scope from the tool name and title.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus guia_status, guia_diagnose, or guia_plan_gather. The agent is not told which situations call for a performance snapshot.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

guia_plan_gatherPropose a bounded companion missionA
Read-only

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

NameRequiredDescriptionDefault
messageYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already declares the safety profile, and the description reinforces it with 'non-executing plan. No gameplay actions.' That is useful confirmation. But it omits the 180-character input bound, what the returned plan looks like, and how non-Spanish or malformed input is handled, so it adds only moderate behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two terse sentences, front-loaded with the core action and followed by the key constraint. Every phrase earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read-only tool, the description covers the core intent and the non-executing guarantee. Yet with no output schema, it should explain what the 'plan' contains and what happens for invalid input; those gaps leave the agent under-informed about results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the 'message' parameter is undocumented structurally. The description compensates by indicating the input is a Spanish request, giving real meaning to 'message'. However, it doesn't address the maxLength 180 constraint or expected format beyond 'Spanish request'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: it parses a Spanish request into a non-executing plan. This is distinguishable from the siblings (status, performance, diagnose), which are unrelated functions. However, it does not explicitly differentiate itself from them or clarify how the 'plan' relates to the title's 'companion mission'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'No gameplay actions' serves as a partial exclusion, telling the agent this is not for executing gameplay. But there is no explicit when-to-use guidance or reference to the sibling tools, leaving usage largely implied by the 'parse a Spanish request' phrasing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

guia_statusMinecraft world statusA
Read-only

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

NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already indicates this is a safe read operation, but the description adds meaningful context: the status is sanitized and does not reveal player names. It also reinforces that the world is not changed, which is consistent with the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single compact sentence with no wasted words. It front-loads the core action (read sanitized status) and then adds the key behavioral constraints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter, read-only status tool, the definition provides enough context to invoke it safely. The absence of an output schema means the exact returned fields are unspecified, but the description's privacy and no-mutation notes cover the main agent concerns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there is no parameter semantics to document. The baseline for no-parameter tools is 4, and the description does not introduce confusion.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The title identifies the resource as Minecraft world status, and the description states the action as reading sanitized status. Combined, the tool's purpose is clear, though the description alone does not explicitly distinguish it from siblings like guia_performance or guia_diagnose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives such as guia_performance or guia_diagnose. It states behavioral constraints but does not frame them as usage conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 4 tool updatesv0.1.0
    • First observedguia_diagnose
    • First observedguia_performance
    • First observedguia_plan_gather
    • First observedguia_status

TDQS

A3.6/5.0

Scored across 4 tools

Disambiguation4/5

The four tools have mostly distinct roles: status reading, performance metrics reading, diagnosis interpretation, and request-to-plan parsing. However, guia_status, guia_performance, and guia_diagnose all operate on telemetry and could be confused when an agent just wants 'the current situation.' The descriptions help, but boundaries are not perfectly sharp.

Naming Consistency4/5

All tools share the guia_ prefix and snake_case style, giving a predictable namespace. The second component is less uniform: status and performance are noun-like read targets, diagnose is a verb, and plan_gather is a compound action. This is a minor deviation rather than a real inconsistency.

Tool Count5/5

Four tools is well within the appropriate range for a focused advisory/diagnostics server. Each tool has a clear place: status, metrics, diagnosis, and planning. Nothing feels redundant or bloated.

Completeness4/5

The read-only, non-executing scope is coherent and covered by status, performance, diagnosis, and plan gathering. There are minor gaps around discovering what telemetry or plan types are available, but the surface supports the stated safe-advisory purpose without obvious dead ends.

Maintenance

ActivityMaintained
ResponsivenessResponsive

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    B
    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