Minecraft Bedrock MCP Server

Instructions

Implementation Reference

• src/tools/core/minecraft-wiki.ts:84-159 (handler)

  The primary handler method that processes input arguments, dispatches to specific wiki operations based on the 'action' parameter (search, get_page, get_section, sequence), calls helper methods, and returns structured ToolCallResult.

  async execute(args: {
      action: string;
      query?: string;
      page_title?: string;
      title?: string;
      section?: string;
      focus?: string;
      steps?: SequenceStep[];
  }): Promise<ToolCallResult> {
      try {
          const { action } = args;
          let result: any;
          let message: string;
  
          switch (action) {
              case 'search':
                  if (!args.query) {
                      return { success: false, message: 'Query required for search action' };
                  }
                  result = await this.searchWiki(args.query, args.focus);
                  message = `Wiki search completed for: "${args.query}"`;
                  break;
  
              case 'get_page':
                  const pageTitle = args.page_title || args.title;
                  if (!pageTitle) {
                      return { success: false, message: 'Page title required for get_page action' };
                  }
                  result = await this.getPageContent(pageTitle);
                  message = `Retrieved wiki page: "${pageTitle}"`;
                  break;
  
              case 'get_page_summary':
                  const summaryTitle = args.page_title || args.title;
                  if (!summaryTitle) {
                      return { success: false, message: 'Page title required for get_page_summary action' };
                  }
                  result = await this.getPageSummary(summaryTitle);
                  message = `Retrieved wiki page summary: "${summaryTitle}"`;
                  break;
  
              case 'get_section':
                  const sectionPageTitle = args.page_title || args.title;
                  if (!sectionPageTitle || !args.section) {
                      return { success: false, message: 'Page title and section required for get_section action' };
                  }
                  result = await this.getPageSection(sectionPageTitle, args.section);
                  message = `Retrieved section "${args.section}" from page "${sectionPageTitle}"`;
                  break;
  
              case 'sequence':
                  if (!args.steps) {
                      return this.createErrorResponse('steps array is required for sequence action');
                  }
                  return await this.executeSequence(args.steps as SequenceStep[]);
  
              default:
                  return { 
                      success: false, 
                      message: `Unknown action: ${action}. Supported actions: search, get_page, get_page_summary, get_section, sequence` 
                  };
          }
  
          return {
              success: true,
              message: message,
              data: { action, result, timestamp: Date.now() }
          };
  
      } catch (error) {
          return {
              success: false,
              message: `Minecraft Wiki search error: ${error instanceof Error ? error.message : String(error)}`
          };
      }
  }

• src/tools/core/minecraft-wiki.ts:13-70 (schema)

  Defines the input schema with required 'action' and optional parameters for querying the Minecraft Wiki, including support for sequence steps.

  readonly inputSchema: InputSchema = {
      type: 'object',
      properties: {
          action: {
              type: 'string',
              description: 'Wiki search action to perform',
              enum: ['search', 'get_page', 'get_page_summary', 'get_section', 'sequence']
          },
          query: {
              type: 'string',
              description: 'Search query (e.g., "give command", "diamond sword", "teleport", "setblock")'
          },
          page_title: {
              type: 'string',
              description: 'Specific wiki page title to retrieve'
          },
          title: {
              type: 'string',
              description: 'Wiki page title (alternative parameter name for compatibility)'
          },
          section: {
              type: 'string',
              description: 'Specific section name within a page'
          },
          focus: {
              type: 'string',
              description: 'Focus area for search results',
              enum: ['commands', 'blocks', 'items', 'entities', 'mechanics', 'bedrock_edition', 'education_edition']
          },
          steps: {
              type: 'array',
              description: 'Array of wiki search actions for sequence. Example: [{"type":"search","query":"give command","focus":"commands"},{"type":"get_page","title":"Commands/give"},{"type":"get_section","title":"Commands/give","section":"Syntax"}]. Use this to break down information gathering into manageable steps instead of getting overwhelming responses.',
              items: {
                  type: 'object',
                  description: 'Wiki sequence step',
                  properties: {
                      type: {
                          type: 'string',
                          enum: ['search', 'get_page', 'get_page_summary', 'get_section', 'wait'],
                          description: 'Wiki action type'
                      },
                      query: { type: 'string', description: 'Search query for search action' },
                      title: { type: 'string', description: 'Page title for get_page/get_section actions' },
                      page_title: { type: 'string', description: 'Alternative page title parameter' },
                      section: { type: 'string', description: 'Section name for get_section action' },
                      focus: { 
                          type: 'string', 
                          enum: ['commands', 'blocks', 'items', 'entities', 'mechanics', 'bedrock_edition', 'education_edition'],
                          description: 'Search focus area' 
                      },
                      wait_time: { type: 'number', description: 'Wait time in seconds after this step' }
                  },
                  required: ['type']
              }
          }
      },
      required: ['action']
  };

• src/server.ts:357-357 (registration)

  Instantiation of the MinecraftWikiTool class and addition to the central tools array during server initialization.

  new MinecraftWikiTool(),

• src/server.ts:494-573 (registration)

  Loop that registers all modular tools (including minecraft_wiki) to the MCP server by converting inputSchema to Zod schema and providing a wrapper around the tool's execute method.

  this.tools.forEach((tool) => {
    // inputSchemaをZod形式に変換（SchemaToZodConverterを使用）
    const zodSchema = schemaConverter.convert(tool.inputSchema);
  
    // ツールを登録
    this.mcpServer.registerTool(
      tool.name,
      {
        title: tool.name,
        description: tool.description,
        inputSchema: zodSchema,
      },
      async (args: any) => {
        try {
          const result = await tool.execute(args);
  
          let responseText: string;
  
          if (result.success) {
            // 建築ツールの場合は最適化
            if (tool.name.startsWith('build_')) {
              const optimized = optimizeBuildResult(result);
              responseText = `✅ ${optimized.message}`;
              if (optimized.summary) {
                responseText += `\n\n📊 Summary:\n${JSON.stringify(optimized.summary, null, 2)}`;
              }
            } else {
              // 通常ツールの場合
              responseText = result.message || `Tool ${tool.name} executed successfully`;
              if (result.data) {
                // データサイズチェック
                const dataStr = JSON.stringify(result.data, null, 2);
                const sizeWarning = checkResponseSize(dataStr);
  
                if (sizeWarning) {
                  // 大きすぎる場合はデータタイプのみ表示
                  responseText += `\n\n${sizeWarning}`;
                  responseText += `\nData type: ${Array.isArray(result.data) ? `Array[${result.data.length}]` : typeof result.data}`;
                } else {
                  responseText += `\n\nData: ${dataStr}`;
                }
              }
            }
          } else {
            // エラーメッセージにヒントを追加
            const errorMsg = result.message || "Tool execution failed";
            const enrichedError = enrichErrorWithHints(errorMsg);
            responseText = `❌ ${enrichedError}`;
            if (result.data) {
              responseText += `\n\nDetails:\n${JSON.stringify(result.data, null, 2)}`;
            }
          }
  
          return {
            content: [
              {
                type: "text",
                text: responseText,
              },
            ],
          };
        } catch (error) {
          const errorMsg =
            error instanceof Error ? error.message : String(error);
          const errorStack = error instanceof Error ? error.stack : undefined;
  
          const exceptionMessage = `Tool execution failed with exception: ${errorMsg}${errorStack ? `\n\nStack trace:\n${errorStack}` : ""}`;
  
          return {
            content: [
              {
                type: "text",
                text: `❌ ${exceptionMessage}`,
              },
            ],
          };
        }
      }
    );
  });

• src/tools/core/minecraft-wiki.ts:168-210 (helper)

  Core utility method for making authenticated and timed API calls to the Minecraft Wiki MediaWiki API.

  private async callMediaWikiAPI(params: Record<string, string>): Promise<any> {
      const baseParams = {
          format: 'json',
          origin: '*',
          ...params
      };
      
      const url = `https://minecraft.wiki/api.php?${new URLSearchParams(baseParams)}`;
      
      try {
          // タイムアウト付きでfetch APIを使用
          const controller = new AbortController();
          const timeoutId = setTimeout(() => controller.abort(), 8000); // 8秒タイムアウト
          
          const response = await fetch(url, {
              method: 'GET',
              headers: {
                  'User-Agent': 'Minecraft-Bedrock-MCP-Server/1.0',
                  'Accept': 'application/json'
              },
              signal: controller.signal
          });
          
          clearTimeout(timeoutId);
          
          if (!response.ok) {
              throw new Error(`HTTP ${response.status}: ${response.statusText}`);
          }
          
          const data = await response.json() as any;
          
          if (data.error) {
              throw new Error(`MediaWiki API Error: ${data.error.info || data.error.code}`);
          }
          
          return data;
      } catch (error) {
          if (error instanceof Error && error.name === 'AbortError') {
              throw new Error('MediaWiki API request timed out (8 seconds)');
          }
          throw new Error(`MediaWiki API call failed: ${error instanceof Error ? error.message : String(error)}`);
      }
  }