HUMMBL MCP Server

Instructions

Implementation Reference

• src/tools/methodology.ts:68-143 (registration)

  Full registration of the MCP 'audit_model_references' tool, including description, Zod input/output schemas, and the inline async handler function that processes the request and calls the core audit logic.
  // Tool: Audit model references against HUMMBL Base120 and methodology expectations server.registerTool( "audit_model_references", { title: "Audit HUMMBL Model References", description: "Audit a list of HUMMBL model references for existence, transformation alignment, and duplicates.", inputSchema: z.object({ items: z .array( z.object({ code: z.string().min(2).describe("Model code, e.g., IN11, CO4"), expectedTransformation: z .enum(["P", "IN", "CO", "DE", "RE", "SY"]) .optional() .describe("Optional expected transformation key for this reference"), }) ) .min(1), }), outputSchema: z.object({ methodologyId: z.string(), documentVersion: z.string(), totalReferences: z.number(), validCount: z.number(), invalidCount: z.number(), issues: z.array( z.object({ code: z.string(), issueType: z.enum(["NotFound", "WrongTransformation", "Duplicate", "Unknown"]), message: z.string(), expectedTransformation: z.string().optional(), actualTransformation: z.string().optional(), }) ), }), }, async ({ items }) => { const auditItems: AuditInputItem[] = items.map((item) => ({ code: item.code, expectedTransformation: item.expectedTransformation, })); const result = auditModelCodes(auditItems); if (!isOk(result)) { const error = result.error; const baseMessage = error.type === "ValidationError" ? error.message : `Unable to audit model references: ${error.type}`; return { content: [ { type: "text" as const, text: baseMessage, }, ], isError: true as const, }; } const payload = result.value; return { content: [ { type: "text" as const, text: JSON.stringify(payload, null, 2), }, ], structuredContent: payload as unknown as { [key: string]: unknown }, }; } );
• src/framework/self_dialectical.ts:91-170 (handler)

  Core handler logic for auditing model references: normalizes codes, checks existence and transformation type using Base120 data, detects duplicates, computes statistics and issues list.
  export function auditModelCodes( items: AuditInputItem[] ): Result<MethodologyAuditResult, DomainError> { if (items.length === 0) { return err({ type: "ValidationError", field: "codes", message: "At least one model code must be provided for audit.", }); } const normalizedItems = items.map((item) => ({ code: item.code.toUpperCase(), expectedTransformation: item.expectedTransformation, })); const issues: ModelReferenceIssue[] = []; let validCount = 0; const seen = new Map<string, number>(); for (const item of normalizedItems) { const currentCount = seen.get(item.code) ?? 0; seen.set(item.code, currentCount + 1); } for (const item of normalizedItems) { const modelResult = getModelByCode(item.code); if (!modelResult.ok) { issues.push({ code: item.code, issueType: "NotFound", message: `Model code '${item.code}' was not found in HUMMBL Base120.`, }); continue; } validCount += 1; const model = modelResult.value; const owningTransformationKey = findTransformationKeyForModel(model.code); if (item.expectedTransformation && owningTransformationKey) { if (owningTransformationKey !== item.expectedTransformation) { issues.push({ code: item.code, issueType: "WrongTransformation", message: `Model '${item.code}' belongs to transformation '${owningTransformationKey}', not '${item.expectedTransformation}'.`, expectedTransformation: item.expectedTransformation, actualTransformation: owningTransformationKey, }); } } const count = seen.get(item.code) ?? 0; if (count > 1) { issues.push({ code: item.code, issueType: "Duplicate", message: `Model code '${item.code}' appears ${count} times in the provided references.`, }); } } const totalReferences = normalizedItems.length; const invalidCount = issues.length; const result: MethodologyAuditResult = { methodologyId: METHODOLOGY_ID, documentVersion: METHODOLOGY_VERSION, totalReferences, validCount, invalidCount, issues, }; return ok(result); }
• src/framework/self_dialectical.ts:86-89 (schema)

  Type definition for audit input items, used in tool input schema and handler mapping.
  export interface AuditInputItem { code: string; expectedTransformation?: TransformationType; }
• src/framework/self_dialectical.ts:172-201 (helper)

  Helper functions to find the owning transformation key for a model code by scanning Base120 transformations.
  function findTransformationKeyForModel(code: string): TransformationType | undefined { const transformationResult = getTransformationByKeyForModel(code); if (!transformationResult.ok) { return undefined; } return transformationResult.value; } function getTransformationByKeyForModel(code: string): Result<TransformationType, DomainError> { // We scan transformations to find which one owns this model. // Using base120 helpers keeps all logic in the framework layer. const possibleKeys: TransformationType[] = ["P", "IN", "CO", "DE", "RE", "SY"]; for (const key of possibleKeys) { const transResult = getTransformationByKey(key); if (!transResult.ok) { continue; } const transformation = transResult.value; if (transformation.models.some((m) => m.code === code)) { return ok(key); } } return err({ type: "NotFound", entity: "Transformation", code, }); }