iz-tolk-mcp

Instructions

Implementation Reference

• src/tools.ts:163-202 (handler)

  Main handler function for check_tolk_syntax tool. Validates input sources, runs the Tolk compiler to check for syntax/type errors, and returns either 'OK' with code hash or detailed error messages. Uses optimization level 2 and suppresses full compilation output for faster feedback.

  async (args) => {
    const { sources, entrypointFileName } = args;
  
    const validationError = validateSources(sources, entrypointFileName);
    if (validationError) {
      return {
        content: [{ type: "text", text: `Validation error: ${validationError}` }],
        isError: true,
      };
    }
  
    try {
      const result = await runTolkCompiler({
        entrypointFileName,
        fsReadCallback: makeFsReadCallback(sources),
        optimizationLevel: 2,
        withStackComments: false,
        experimentalOptions: undefined,
      });
  
      if (result.status === "error") {
        return {
          content: [{ type: "text", text: `Syntax/type error:\n\n${result.message}` }],
          isError: true,
        };
      }
  
      let text = `OK — no errors found.\n\n**Code hash:** \`${result.codeHashHex}\``;
      if (result.stderr && result.stderr.length > 0) {
        text += `\n\n### Warnings\n\`\`\`\n${result.stderr}\n\`\`\``;
      }
  
      return { content: [{ type: "text", text }] };
    } catch (err: any) {
      return {
        content: [{ type: "text", text: `Unexpected compiler error: ${err.message}` }],
        isError: true,
      };
    }
  },

• src/tools.ts:154-162 (schema)

  Input schema definition for check_tolk_syntax using zod. Requires 'entrypointFileName' (string, e.g., 'main.tolk') and 'sources' (Record<string, string> mapping filenames to source code content).

  {
    entrypointFileName: z.string().describe('The main .tolk file to check (e.g., "main.tolk")'),
    sources: z
      .record(z.string(), z.string())
      .describe(
        "Object mapping filename -> source code content. Must include the entrypoint file. " +
          'Example: {"main.tolk": "fun main(): int { return 0; }"}',
      ),
  },

• src/tools.ts:150-203 (registration)

  Complete tool registration with MCP server. Includes tool name 'check_tolk_syntax', description explaining it checks syntax/type errors without full compilation, input schema, and the async handler function.

  server.tool(
    "check_tolk_syntax",
    "Checks Tolk source code for syntax and type errors without returning full compilation output. " +
      "Faster feedback loop for iterative development. Returns OK + code hash on success, or error details on failure.",
    {
      entrypointFileName: z.string().describe('The main .tolk file to check (e.g., "main.tolk")'),
      sources: z
        .record(z.string(), z.string())
        .describe(
          "Object mapping filename -> source code content. Must include the entrypoint file. " +
            'Example: {"main.tolk": "fun main(): int { return 0; }"}',
        ),
    },
    async (args) => {
      const { sources, entrypointFileName } = args;
  
      const validationError = validateSources(sources, entrypointFileName);
      if (validationError) {
        return {
          content: [{ type: "text", text: `Validation error: ${validationError}` }],
          isError: true,
        };
      }
  
      try {
        const result = await runTolkCompiler({
          entrypointFileName,
          fsReadCallback: makeFsReadCallback(sources),
          optimizationLevel: 2,
          withStackComments: false,
          experimentalOptions: undefined,
        });
  
        if (result.status === "error") {
          return {
            content: [{ type: "text", text: `Syntax/type error:\n\n${result.message}` }],
            isError: true,
          };
        }
  
        let text = `OK — no errors found.\n\n**Code hash:** \`${result.codeHashHex}\``;
        if (result.stderr && result.stderr.length > 0) {
          text += `\n\n### Warnings\n\`\`\`\n${result.stderr}\n\`\`\``;
        }
  
        return { content: [{ type: "text", text }] };
      } catch (err: any) {
        return {
          content: [{ type: "text", text: `Unexpected compiler error: ${err.message}` }],
          isError: true,
        };
      }
    },
  );

• src/tools.ts:9-33 (helper)

  validateSources helper function used by check_tolk_syntax. Ensures sources map is not empty, file count doesn't exceed MAX_FILE_COUNT (50), entrypoint file exists in sources, and total size doesn't exceed MAX_TOTAL_SIZE (1MB). Returns error message or null on success.

  function validateSources(sources: Record<string, string>, entrypointFileName: string): string | null {
    const keys = Object.keys(sources);
  
    if (keys.length === 0) {
      return "sources is empty. Provide at least the entrypoint file.";
    }
  
    if (keys.length > MAX_FILE_COUNT) {
      return `Too many source files (${keys.length}). Maximum is ${MAX_FILE_COUNT}.`;
    }
  
    if (!(entrypointFileName in sources)) {
      return `Entrypoint file "${entrypointFileName}" not found in sources. ` + `Available files: ${keys.join(", ")}`;
    }
  
    let totalSize = 0;
    for (const content of Object.values(sources)) {
      totalSize += new TextEncoder().encode(content).byteLength;
    }
    if (totalSize > MAX_TOTAL_SIZE) {
      return `Total sources size (${totalSize} bytes) exceeds limit of ${MAX_TOTAL_SIZE} bytes.`;
    }
  
    return null;
  }

• src/tools.ts:35-45 (helper)

  makeFsReadCallback helper function that creates a file system callback for the Tolk compiler. Normalizes file paths (handles './' prefix) and returns file contents from the sources map, throwing descriptive errors for missing files.

  function makeFsReadCallback(sources: Record<string, string>) {
    return (path: string): string => {
      const normalized = path.startsWith("./") ? path.slice(2) : path;
      if (sources[normalized] !== undefined) return sources[normalized];
      if (sources[path] !== undefined) return sources[path];
      throw new Error(
        `File not found: ${path} (available: ${Object.keys(sources).join(", ")}). ` +
          `Note: @stdlib/* imports are resolved automatically by the compiler.`,
      );
    };
  }