check_tolk_syntax

Instructions

Implementation Reference

• src/tools.ts:163-224 (registration)

  Registration of the 'check_tolk_syntax' tool via server.tool() calls on the MCP server.

  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. Supports pathMappings for custom @alias import resolution. " +
      "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; }"}',
        ),
      pathMappings: z
        .record(z.string(), z.string())
        .optional()
        .describe(
          "Maps @alias prefixes to absolute folder paths for import resolution. " +
            'Example: {"@mylib": "/path/to/mylib"}',
        ),
    },
    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,
          ...(args.pathMappings ? { pathMappings: args.pathMappings } : {}),
        });
  
        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) {
        return {
          content: [{ type: "text", text: `Unexpected compiler error: ${getErrorMessage(err)}` }],
          isError: true,
        };
      }
    },
  );

• src/tools.ts:168-183 (schema)

  Zod schema definitions for check_tolk_syntax input parameters: entrypointFileName (string), sources (record of strings), optional pathMappings (record of strings).

  {
    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; }"}',
      ),
    pathMappings: z
      .record(z.string(), z.string())
      .optional()
      .describe(
        "Maps @alias prefixes to absolute folder paths for import resolution. " +
          'Example: {"@mylib": "/path/to/mylib"}',
      ),
  },

• src/tools.ts:184-223 (handler)

  Handler function for check_tolk_syntax: validates sources, runs the Tolk compiler (syntax-only mode with optimizationLevel=2, no stack comments), returns OK+code hash on success or syntax/type error details on failure.

  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,
        ...(args.pathMappings ? { pathMappings: args.pathMappings } : {}),
      });
  
      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) {
      return {
        content: [{ type: "text", text: `Unexpected compiler error: ${getErrorMessage(err)}` }],
        isError: true,
      };
    }
  },