codecks-mcp

Instructions

Implementation Reference

• src/tools/registry.ts:151-179 (handler)

  The main handler function for get_tag_registry tool. Filters tags by optional category parameter and returns tag definitions, count, hero_tags, and lane_tags in a formatted response.

  async (args) => {
    let tags = TAGS;
    if (args.category) {
      tags = tags.filter((t) => t.category === args.category);
    }
  
    const tagDicts = tags.map((t) => ({
      name: t.name,
      display_name: t.displayName,
      category: t.category,
      description: t.description,
    }));
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            finalizeToolResult({
              tags: tagDicts,
              count: tagDicts.length,
              hero_tags: [...HERO_TAGS],
              lane_tags: LANE_TAGS,
            }),
          ),
        },
      ],
    };
  },

• src/tools/registry.ts:137-180 (registration)

  Tool registration using server.registerTool() with name 'get_tag_registry', including title, description, input schema, and async handler callback.

  export function registerRegistryTools(server: McpServer): void {
    server.registerTool(
      "get_tag_registry",
      {
        title: "Get Tag Registry",
        description:
          "Get the local tag taxonomy (definitions, hero tags, lane-tag mappings). No auth needed.",
        inputSchema: z.object({
          category: z
            .enum(["system", "discipline"])
            .optional()
            .describe("Filter to system or discipline tags only"),
        }),
      },
      async (args) => {
        let tags = TAGS;
        if (args.category) {
          tags = tags.filter((t) => t.category === args.category);
        }
  
        const tagDicts = tags.map((t) => ({
          name: t.name,
          display_name: t.displayName,
          category: t.category,
          description: t.description,
        }));
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                finalizeToolResult({
                  tags: tagDicts,
                  count: tagDicts.length,
                  hero_tags: [...HERO_TAGS],
                  lane_tags: LANE_TAGS,
                }),
              ),
            },
          ],
        };
      },
    );

• src/tools/registry.ts:140-149 (schema)

  Input schema definition using zod with an optional 'category' parameter that accepts 'system' or 'discipline' enum values for filtering tags.

  {
    title: "Get Tag Registry",
    description:
      "Get the local tag taxonomy (definitions, hero tags, lane-tag mappings). No auth needed.",
    inputSchema: z.object({
      category: z
        .enum(["system", "discipline"])
        .optional()
        .describe("Filter to system or discipline tags only"),
    }),

• src/tools/registry.ts:14-78 (helper)

  Supporting data structures: TagDefinition interface, TAGS array with 8 tag definitions, HERO_TAGS set, and LANE_TAGS mapping used by the get_tag_registry handler.

  interface TagDefinition {
    name: string;
    displayName: string;
    category: "system" | "discipline";
    description: string;
  }
  
  const TAGS: TagDefinition[] = [
    {
      name: "feature",
      displayName: "Feature",
      category: "system",
      description: "New functionality",
    },
    {
      name: "bug",
      displayName: "Bug",
      category: "system",
      description: "Defect to fix",
    },
    {
      name: "chore",
      displayName: "Chore",
      category: "system",
      description: "Maintenance task",
    },
    {
      name: "spike",
      displayName: "Spike",
      category: "system",
      description: "Research/investigation",
    },
    {
      name: "code",
      displayName: "Code",
      category: "discipline",
      description: "Programming work",
    },
    {
      name: "design",
      displayName: "Design",
      category: "discipline",
      description: "Visual/UX design",
    },
    {
      name: "art",
      displayName: "Art",
      category: "discipline",
      description: "Art assets",
    },
    {
      name: "audio",
      displayName: "Audio",
      category: "discipline",
      description: "Sound/music",
    },
  ];
  
  const HERO_TAGS = new Set(["feature", "bug", "chore", "spike"]);
  const LANE_TAGS: Record<string, string[]> = {
    code: ["code"],
    design: ["design"],
    art: ["art"],
    audio: ["audio"],
  };

• src/contract.ts:56-86 (helper)

  The finalizeToolResult helper function that wraps the handler's response in a contract envelope with schema_version and ok status fields.

  export function finalizeToolResult(result: unknown): unknown {
    if (result !== null && typeof result === "object" && !Array.isArray(result)) {
      const dict = result as Record<string, unknown>;
      const normalized = ensureContractDict(dict);
  
      if (normalized.ok === false) return normalized;
  
      if (config.mcpResponseMode === "envelope") {
        const data = { ...normalized };
        delete data.ok;
        delete data.schema_version;
        return {
          ok: true,
          schema_version: CONTRACT_SCHEMA_VERSION,
          data,
        };
      }
  
      return normalized;
    }
  
    if (config.mcpResponseMode === "envelope") {
      return {
        ok: true,
        schema_version: CONTRACT_SCHEMA_VERSION,
        data: result,
      };
    }
  
    return result;
  }