MarkdownLM MCP Server

Instructions

Implementation Reference

• src/index.ts:219-227 (handler)

  The resolve_gap tool handler that validates input parameters (question and category), calls the API client's resolveGap method, logs the outcome, and returns the result in the MCP response format.

  case 'resolve_gap': {
    const question = requireString(safeArgs, 'question')
    if (!question) { log(toolName, safeArgs, 'error', 'missing question'); return err('question is required') }
    const category = requireString(safeArgs, 'category')
    if (!category) { log(toolName, safeArgs, 'error', 'missing category'); return err('category is required') }
    const result = await client.resolveGap({ question, category })
    log(toolName, { question, category }, 'ok')
    return ok(result)
  }

• src/index.ts:132-171 (registration)

  Tool registration and schema definition for resolve_gap, including the tool's name, description, input schema (question and category fields with enum for categories), and usage instructions for when to call this tool.

  {
    name: 'resolve_gap',
    description:
      "Call this when query_knowledge_base returned no documented guidance for a decision you need to make. " +
      "Logs the undocumented decision as a knowledge gap so the developer can review and document it. " +
      "Returns how you should proceed based on the team's configured gap policy: " +
      '"ask_user" = stop and ask the developer for a decision before continuing; ' +
      '"infer" = MarkdownLM has auto-resolved the gap, use the returned resolution value; ' +
      '"agent_decide" = proceed with your best judgement and document your reasoning. ' +
      'Do NOT call this if query_knowledge_base returned matching rules — it is only for genuinely undocumented decisions.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        question: {
          type: 'string',
          description:
            'The specific undocumented decision you need to make, phrased as a question. ' +
            'Be precise so the developer understands exactly what is missing from the knowledge base. ' +
            'Example: "Which HTTP client library should I use for server-side requests — axios, got, or native fetch?"',
        },
        category: {
          type: 'string',
          enum: [
            'architecture',
            'stack',
            'testing',
            'deployment',
            'security',
            'style',
            'dependencies',
            'error_handling',
            'business_logic',
            'general',
          ],
          description: 'Category that best describes the gap. Helps the developer triage and document the missing rule.',
        },
      },
      required: ['question', 'category'],
    },
  },

• src/lib/api-client.ts:126-131 (handler)

  The API client method resolveGap that makes a POST request to the /gaps/detect endpoint with the question and category parameters, returning a ResolveGapResult with resolution mode and optional resolution value.

  async resolveGap(input: ResolveGapInput): Promise<ResolveGapResult> {
    return this.request<ResolveGapResult>('/gaps/detect', {
      query: input.question,
      ...(input.category ? { category: input.category } : {}),
    })
  }

• src/lib/api-client.ts:22-32 (schema)

  Type definitions for resolve_gap: ResolveGapInput interface defining question and category fields, and ResolveGapResult interface defining the response structure with gap_detected, resolution_mode, resolution, and gap_id fields.

  export interface ResolveGapInput {
    question: string
    category: string
  }
  
  export interface ResolveGapResult {
    gap_detected: boolean
    resolution_mode: 'markdownlm' | 'ask_user' | 'agent_decide' | 'none'
    resolution?: string
    gap_id?: string
  }