Set Up Knowledge Base

Add semantic search over markdown documents to an MCP project using the Waniwani KB API (client.kb).

Prerequisites

• Project must already be initialized (no {{MCP_NAME}} placeholders)
• @waniwani/sdk must be installed
• WANIWANI_API_KEY must be set in the environment

Steps

1. Detect MCP name

Look in lib/ for the directory that isn't shared — that's the MCP name. Store as {MCP_NAME}.

2. Create knowledge directory

Create lib/{MCP_NAME}/knowledge-base/knowledge/ directory.

Ask the user: "Do you have .md files to add to the knowledge base, or should I create an example file?"

If no files provided, create lib/{MCP_NAME}/knowledge-base/knowledge/example.md:

# Example Knowledge Base

## What is this?

This is an example knowledge base entry. Replace this file with your own .md files containing information you want your AI assistant to be able to search through.

## How does it work?

Each .md file is split into chunks by H2 headings. The H1 title provides context for each chunk. Run `bun run kb:ingest` to upload your knowledge files to the Waniwani API.

3. Create the ingestion script

Create scripts/kb-ingest.ts (create scripts/ directory if it doesn't exist):

import { readdir, readFile } from "node:fs/promises";
import { join } from "node:path";
import { waniwani } from "@waniwani/sdk";

const knowledgeDir = join(import.meta.dirname, "../lib/{MCP_NAME}/knowledge-base/knowledge");

const mdFiles = (await readdir(knowledgeDir)).filter((f) => f.endsWith(".md"));
console.log(`Found ${mdFiles.length} knowledge file(s)`);

const files = await Promise.all(
  mdFiles.map(async (filename) => ({
    filename,
    content: await readFile(join(knowledgeDir, filename), "utf-8"),
  })),
);

const client = waniwani();

console.log("Ingesting files into knowledge base...");
console.log("Files land in the agent's draft. Publish it in the WaniWani app to make them live.");

const result = await client.kb.ingest(files);
console.log(`Done: ${result.chunksIngested} chunks from ${result.filesProcessed} files`);

4. Add ingest script to package.json

Add to scripts:

"kb:ingest": "bun run scripts/kb-ingest.ts"

5. Create the FAQ tool

A KB lookup is a single-shot tool, not a multi-step flow, so register it directly on the MCP server. withWaniwani wraps the server to capture tool.called and hand the handler a session-scoped client.

Create lib/{MCP_NAME}/tools/faq.ts:

import { waniwani } from "@waniwani/sdk";
import type { McpServer } from "@waniwani/sdk/mcp";
import { z } from "zod";

const client = waniwani();

export function registerFaqTool(server: McpServer): void {
  server.registerTool(
    "faq",
    {
      title: "FAQ",
      description:
        "Answer frequently asked questions. Use this when users ask general questions about the product or service.",
      inputSchema: {
        question: z.string().describe("The user's question"),
      },
      annotations: {
        title: "FAQ",
        readOnlyHint: true,
        openWorldHint: false,
        destructiveHint: false,
      },
    },
    async ({ question }) => {
      const results = await client.kb.search(question, { topK: 5 });

      if (results.length === 0) {
        return {
          content: [
            {
              type: "text" as const,
              text: "I don't have a specific answer for that question.",
            },
          ],
        };
      }

      const text = results
        .map((r) => `**${r.heading}**\n${r.content}`)
        .join("\n\n---\n\n");

      return { content: [{ type: "text" as const, text }] };
    },
  );
}

annotations.title is required by Claude's Connectors Directory, which flags the server at submission without it. The top-level title does not satisfy it.

6. Register the FAQ tool

Export from lib/{MCP_NAME}/tools/index.ts:

export { registerFaqTool } from "./faq";

Call it where the server is built, inside the withWaniwani wrapper:

import { withWaniwani } from "@waniwani/sdk/mcp";
import { registerFaqTool } from "@/lib/{MCP_NAME}/tools";

const server = withWaniwani(new McpServer({ name: "{MCP_NAME}", version: "1.0.0" }));
registerFaqTool(server);

7. Ingest knowledge files

bun run kb:ingest

This requires WANIWANI_API_KEY to be set in the environment.

8. Verify

bun run build

9. Print summary

Tell the user:

• Knowledge files go in: lib/{MCP_NAME}/knowledge-base/knowledge/
• Run bun run kb:ingest after adding or updating .md files
• WANIWANI_API_KEY must be set in the environment
• Markdown files should use # Title (H1) and ## Section (H2) structure
• A push replaces only the sources it names and lands in the agent's draft. Publish in the app to make it live.