mc-develop-first

mc_develop First

mc_develop is the evidence and capability gateway for Minecraft work. A new agent should not treat it as a keyword search box. Use its structured fields to ask for the exact capability you need, then use normal tools only for file reads, edits, builds, tests, diffs, and commits after MCP evidence points there.

Operating Rule

For Minecraft tasks:

1. Call mc_develop before technical advice, code edits, datapack JSON edits, crash diagnoses, dependency coordinates, or docs claims.
2. If you know the desired capability, use operations[].kind plus the matching structured field.
3. Put exact ids, versions, paths, classes, resource locations, symbols, docs topics, and policies into structured fields, not only into requestText.
4. Treat requestText as human context and fallback only.
5. Read the structured result before acting. If evidence is missing, make the next MCP call more specific instead of guessing.

First Call Pattern

Use broad auto-detection only when the task is genuinely unclear:

{
  "requestText": "Short exact summary of the Minecraft task.",
  "workspaceRoot": "/absolute/path/to/project-or-modpack"
}

When exact intent is known, make the first call structured:

{
  "requestText": "Human context only.",
  "workspaceRoot": "/absolute/path/to/workspace",
  "operations": [
    {
      "kind": "docs_lookup",
      "docsQuery": "NeoForge register event 1.21"
    }
  ]
}

Always include the per-instance roots you know:

{
  "workspaceRoot": "/path/to/workspace",
  "runtimeRoot": "/path/to/runtime",
  "mdmSourcesRoot": "/path/to/consumer-mdm-sources",
  "prismRoot": "/path/to/PrismLauncher"
}

Reuse runtimeEnvironment.inputPatch from MCP results in follow-up calls.

Capability Map

Use this table before choosing tools or web search.

Supported operations[].kind values:

source_acquisition_plan, workspace_source, probejs_types, mod_archive_content, external_mod_resolution, datapack_files, docs_lookup, log_files, java_diagnostics.

Structured Field Templates

Docs:

{
  "operations": [
    { "kind": "docs_lookup", "docsQuery": "NeoForge capabilities migration 1.21" }
  ]
}

Workspace source:

{
  "operations": [
    {
      "kind": "workspace_source",
      "workspaceSource": {
        "javaSymbols": ["com.example.ExampleMod"],
        "buildFiles": ["build.gradle"]
      }
    }
  ]
}

ProbeJS:

{
  "operations": [
    {
      "kind": "probejs_types",
      "probeJs": {
        "symbol": "event.recipes",
        "resourceQueries": ["minecraft:iron_ingot", "#forge:ingots/iron"],
        "scope": "server"
      }
    }
  ],
  "preparationRoutes": ["workspace_probejs"]
}

ProbeJS resource inventory:

{
  "operations": [
    {
      "kind": "probejs_types",
      "probeJs": {
        "resourceOnly": true,
        "resourceKinds": ["item"],
        "resourceLimitPerKind": 0
      }
    }
  ],
  "preparationRoutes": ["workspace_probejs"]
}

Use resourceLimitPerKind: 0 for counts-only discovery. Omit it for all matching entries, or set an explicit number when the user wants a bounded export. Use resourceKinds and resourceQueries for filtering; do not hide those controls in requestText.

Local mod jars:

{
  "operations": [
    {
      "kind": "mod_archive_content",
      "modArchive": {
        "classOwners": ["com.example.problem.CrashHandler"],
        "inventory": true
      }
    }
  ],
  "preparationRoutes": ["local_jar"],
  "preparationPolicy": { "localJarMode": "prewarm_entry_index" }
}

Datapack/resource-pack:

{
  "operations": [
    {
      "kind": "datapack_files",
      "datapack": {
        "mode": "resource_pack",
        "paths": ["assets/example/models/item/demo.json"],
        "traceReferences": true
      }
    }
  ]
}

External mod exact lookup:

{
  "operations": [
    {
      "kind": "external_mod_resolution",
      "externalModRequests": [
        {
          "platform": "modrinth",
          "projectId": "AANobbMI",
          "slug": "sodium",
          "loader": "neoforge",
          "minecraftVersion": "26.1.2"
        }
      ]
    }
  ],
  "preparationPolicy": { "remoteMetadataPolicy": "enabled" }
}

Unknown External Mods

If slug/project id is unknown, do not pretend query is exact. Use discovery first:

{
  "operations": [
    {
      "kind": "external_mod_resolution",
      "externalModRequests": [
        {
          "platform": "modrinth",
          "query": "Sodium",
          "loader": "neoforge",
          "minecraftVersion": "26.1.2"
        }
      ]
    }
  ],
  "preparationPolicy": { "remoteMetadataPolicy": "enabled" }
}

Then:

• If one high-confidence candidate remains, retry with returned slug and/or projectId.
• If multiple candidates remain, report candidates and ask for confirmation or use local Gradle/jar evidence to disambiguate.
• For CurseForge discovery, credentials are required. If missing, report CURSEFORGE_API_KEY instead of falling back to broad guessing.
• Maven has no universal name search. Prefer exact coordinate, workspace Gradle dependencies, local jars, or repository metadata.

Read references/external-mod-resolution.md for the full two-phase flow.

Read The Result

Always inspect these before editing or answering:

• trace.routeSteps: confirms the MCP actually ran the intended capability.
• executions[].queryHint: should reflect structured fields when exact data was supplied.
• selectedEvidence: the citation set for claims or edits.
• workspacePreparation: route readiness, missing prerequisites, next call patterns.
• runtimeEnvironment.inputPatch: roots to reuse.
• resourceActions and mdmPackageRecommendations: package proposals, not download consent.
• Domain summaries: crashSignals, javaDiagnostics, kubeJsQuality, clientVisualVerifier.

If exact constraints appear only in requestText while queryHint is broad, the call is not reliable enough. Retry with structured fields.

Reference Selection

Read only the relevant reference file:

Normal Tool Boundary

Use normal tools after MCP evidence for:

• Reading exact files named by MCP.
• Editing files.
• Running Gradle, tests, formatters, game/client checks.
• Inspecting diffs, committing, pushing.

Do not use broad rg, jar inspection, web search, or guessed docs as a substitute for MCP routes when MCP can provide that evidence.

Common Failure Modes

• Encoding exact ids or versions only in requestText.
• Treating external query as final resolution.
• Editing KubeJS before ProbeJS evidence.
• Guessing a crash owner from one exception class.
• Mixing Forge/NeoForge/Fabric docs across versions.
• Editing datapack/resource-pack JSON without schema/version evidence.
• Downloading MDM packages without explicit user consent or prior authorization.
• Persisting environment variables globally when runtimeEnvironment.inputPatch is enough.