Cantrip

Instructions

Implementation Reference

• src/tools.ts:64-79 (handler)

  Main handler function for cantrip_connect tool. Checks if project parameter is provided - if yes, writes project context to .cantrip.json; if no, reads current context. Returns connection status with appropriate messages.

  handler: async (p) => {
    if (p.project) {
      writeProjectContext(String(p.project));
      return { connected: true, project: p.project, file: ".cantrip.json" };
    }
    const current = readProjectContext();
    if (current) {
      return { connected: true, project: current };
    }
    return {
      connected: false,
      message:
        "No .cantrip.json found. Call cantrip_connect with a project name, " +
        "or cantrip_init to create a new project.",
    };
  },

• src/tools.ts:58-63 (schema)

  Input schema definition for cantrip_connect using Zod. Defines optional 'project' parameter that accepts a project name string to connect to.

  shape: {
    project: z
      .string()
      .optional()
      .describe("Project name to connect to. Omit to check current connection."),
  },

• src/tools.ts:52-80 (registration)

  Complete tool definition including name 'cantrip_connect', description, schema shape, and handler. Part of the ToolDef array returned by createTools function.

  {
    name: "cantrip_connect",
    description:
      "Start here. Connect this workspace to a Cantrip project by writing a .cantrip.json file. " +
      "All subsequent commands will target this project automatically. " +
      "Call without arguments to check the current connection.",
    shape: {
      project: z
        .string()
        .optional()
        .describe("Project name to connect to. Omit to check current connection."),
    },
    handler: async (p) => {
      if (p.project) {
        writeProjectContext(String(p.project));
        return { connected: true, project: p.project, file: ".cantrip.json" };
      }
      const current = readProjectContext();
      if (current) {
        return { connected: true, project: current };
      }
      return {
        connected: false,
        message:
          "No .cantrip.json found. Call cantrip_connect with a project name, " +
          "or cantrip_init to create a new project.",
      };
    },
  },

• src/server.ts:26-71 (registration)

  Server-side registration of cantrip_connect tool. Marks it as 'noKeyRequired' (line 26) since it works without API key. Registers tool with MCP server using server.tool() method with handler wrapper.

  const noKeyRequired = new Set(["cantrip_status", "cantrip_connect"]);
  
  for (const tool of createTools(client)) {
    server.tool(
      tool.name,
      tool.description,
      tool.shape,
      async (params: Record<string, unknown>) => {
        if (!client.hasApiKey && !noKeyRequired.has(tool.name)) {
          return {
            content: [
              {
                type: "text" as const,
                text:
                  "CANTRIP_API_KEY is not configured. " +
                  "Run cantrip_status for setup instructions, or direct the user to https://cantrip.ai to get a key.",
              },
            ],
            isError: true,
          };
        }
  
        try {
          const result = await tool.handler(params);
          return {
            content: [
              {
                type: "text" as const,
                text: JSON.stringify(result, null, 2),
              },
            ],
          };
        } catch (err) {
          return {
            content: [
              {
                type: "text" as const,
                text: err instanceof Error ? err.message : String(err),
              },
            ],
            isError: true,
          };
        }
      },
    );
  }

• src/client.ts:48-54 (helper)

  writeProjectContext helper function used by cantrip_connect handler. Writes project slug to .cantrip.json file in current working directory as JSON with 2-space indentation.

  export function writeProjectContext(project: string): void {
    writeFileSync(
      getConfigPath(),
      JSON.stringify({ project }, null, 2) + "\n",
      "utf-8",
    );
  }