Skip to content

LLM Wiki is a cross-platform desktop application that turns your documents into an organized, interlinked knowledge base — automatically. Instead of traditional RAG (retrieve-and-answer from scratch every time), the LLM incrementally builds and maintains a persistent wiki from your sources。

TypeScript
24.8 KB
Raw Blame
#!/usr/bin/env node
import { Server } from "@modelcontextprotocol/sdk/server/index.js"
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
import {
  CallToolRequestSchema,
  ErrorCode,
  ListToolsRequestSchema,
  McpError,
} from "@modelcontextprotocol/sdk/types.js"
import {
  LlmWikiApiClient,
  type ApiFileNode,
  type ApiGraphNode,
  type ApiReviewItem,
  type ApiReviewsResponse,
  type ApiChatResponse,
  type ApiSearchResult,
  type ApiProject,
} from "./api-client.js"
import { VERSION } from "./version.js"
import { McpProjectBinding, withActiveProject } from "./project-binding.js"

const DEFAULT_PROJECT_ID = "current"
const MAX_TEXT_BYTES = 120_000
const MAX_WRITE_PAGE_BYTES = 2 * 1024 * 1024

const client = new LlmWikiApiClient()
const projectBinding = new McpProjectBinding()

const server = new Server(
  { name: "llm-wiki", version: VERSION },
  { capabilities: { tools: {} } },
)

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "llm_wiki_status",
      description: "Check whether the LLM Wiki desktop local API is reachable and list the current project.",
      inputSchema: {
        type: "object",
        properties: {},
        additionalProperties: false,
      },
    },
    {
      name: "llm_wiki_projects",
      description: "List known LLM Wiki projects. The response includes currentProject when the desktop app has an active project.",
      inputSchema: {
        type: "object",
        properties: {},
        additionalProperties: false,
      },
    },
    {
      name: "llm_wiki_set_project",
      description: "Pin this MCP process session to one LLM Wiki project. Once pinned, project tools cannot access another project until this tool changes the binding.",
      inputSchema: {
        type: "object",
        properties: {
          project_id: { type: "string", description: "Project UUID, exact filesystem path, or 'current'." },
        },
        required: ["project_id"],
        additionalProperties: false,
      },
    },
    {
      name: "llm_wiki_files",
      description: "List files from a project using the desktop app's API permissions. project_id may be a UUID, filesystem path, or 'current'.",
      inputSchema: {
        type: "object",
        properties: {
          project_id: { type: "string", description: "Project UUID, project path, or 'current'. Defaults to current." },
          root: { type: "string", enum: ["wiki", "sources", "all"], description: "Tree root to list. Defaults to wiki." },
          recursive: { type: "boolean", description: "Whether to list recursively. Defaults to true." },
          max_files: { type: "number", description: "Maximum files returned by the local API. Max 10000." },
        },
        additionalProperties: false,
      },
    },
    {
      name: "llm_wiki_read_file",
      description: "Read a text file from a project through the desktop app API. Only public project paths such as wiki/ and raw/sources/ are allowed by the API.",
      inputSchema: {
        type: "object",
        properties: {
          project_id: { type: "string", description: "Project UUID, project path, or 'current'. Defaults to current." },
          path: { type: "string", description: "Project-relative file path, for example wiki/index.md." },
        },
        required: ["path"],
        additionalProperties: false,
      },
    },
    {
      name: "llm_wiki_reviews",
      description: "List Review tab items from a project. Defaults to unresolved items so agent clients can help manage pending wiki review work.",
      inputSchema: {
        type: "object",
        properties: {
          project_id: { type: "string", description: "Project UUID, project path, or 'current'. Defaults to current." },
          status: { type: "string", enum: ["unresolved", "resolved", "all"], description: "Review status filter. Defaults to unresolved." },
          type: { type: "string", description: "Optional Review item type filter, for example missing-page, duplicate, contradiction, confirm, or suggestion." },
          limit: { type: "number", description: "Maximum review items returned. The local API clamps to its configured maximum." },
        },
        additionalProperties: false,
      },
    },
    {
      name: "llm_wiki_search",
      description: "Search a project using the same backend keyword/vector retrieval used by the desktop API.",
      inputSchema: {
        type: "object",
        properties: {
          project_id: { type: "string", description: "Project UUID, project path, or 'current'. Defaults to current." },
          query: { type: "string", description: "Search query." },
          top_k: { type: "number", description: "Maximum results. The local API clamps to its configured maximum." },
          include_content: { type: "boolean", description: "Include full page content in results when supported by the API." },
        },
        required: ["query"],
        additionalProperties: false,
      },
    },
    {
      name: "llm_wiki_chat",
      description: "Ask the LLM Wiki backend Agent a question about a project. This initial backend Agent uses the desktop API's shared retrieval service and returns references.",
      inputSchema: {
        type: "object",
        properties: {
          project_id: { type: "string", description: "Project UUID, project path, or 'current'. Defaults to current." },
          message: { type: "string", description: "User message or question." },
          session_id: { type: "string", description: "Optional caller-managed session id." },
          mode: { type: "string", enum: ["fast", "standard", "deep", "local_first"], description: "Agent mode. Defaults to standard." },
          top_k: { type: "number", description: "Maximum wiki references to retrieve. The API clamps to its configured maximum." },
          include_content: { type: "boolean", description: "Include full page content in retrieval when supported by the API. Defaults to false." },
          wiki: { type: "boolean", description: "Enable wiki retrieval. Defaults to true." },
          web: { type: "boolean", description: "Enable backend web.search when the Agent router decides external search is useful. Defaults to false." },
          anytxt: { type: "boolean", description: "Enable backend anytxt.search for source/local-file questions when AnyTXT is configured. Defaults to false." },
          skills: {
            type: "array",
            items: { type: "string" },
            description: "Optional project skills to inject from .llm-wiki/skills.",
          },
        },
        required: ["message"],
        additionalProperties: false,
      },
    },
    {
      name: "llm_wiki_graph",
      description: "Query the project knowledge graph through the desktop app API.",
      inputSchema: {
        type: "object",
        properties: {
          project_id: { type: "string", description: "Project UUID, project path, or 'current'. Defaults to current." },
          q: { type: "string", description: "Optional text filter." },
          node_type: { type: "string", description: "Optional node type filter." },
          limit: { type: "number", description: "Maximum nodes. The local API clamps to its configured maximum." },
          offset: { type: "number", minimum: 0, description: "Zero-based node offset." },
          edge_scope: { type: "string", enum: ["page", "filtered"], description: "Use 'page' for self-contained edges or 'filtered' when merging all pages." },
        },
        additionalProperties: false,
      },
    },
    {
      name: "llm_wiki_rescan_sources",
      description: "Trigger the desktop app's source folder rescan for a project, using the user's Source Watch rules.",
      inputSchema: {
        type: "object",
        properties: {
          project_id: { type: "string", description: "Project UUID, project path, or 'current'. Defaults to current." },
        },
        additionalProperties: false,
      },
    },
    {
      name: "llm_wiki_embed_page",
      description: "Create or replace the vector index for one existing Markdown page under a project's wiki/ directory.",
      inputSchema: {
        type: "object",
        properties: {
          project_id: { type: "string", description: "Project UUID, project path, or 'current'. Defaults to current." },
          path: { type: "string", description: "Project-relative Markdown path, for example wiki/ideas/example.md." },
          force: { type: "boolean", description: "Force rebuilding vectors even when the page content and embedding configuration are unchanged." },
        },
        required: ["path"],
        additionalProperties: false,
      },
    },
    {
      name: "llm_wiki_write_page",
      description: "Create or explicitly overwrite one Markdown page under wiki/. Success is returned only after byte-for-byte persistence verification.",
      inputSchema: {
        type: "object",
        properties: {
          project_id: { type: "string", description: "Project UUID, project path, or 'current'. Defaults to current." },
          path: { type: "string", description: "Canonical project-relative Markdown path under wiki/." },
          content: { type: "string", description: "Exact UTF-8 page content to persist." },
          allow_overwrite: { type: "boolean", description: "Defaults to false. Must be true to replace an existing page." },
        },
        required: ["path", "content"],
        additionalProperties: false,
      },
    },
  ],
}))

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const args = asObject(request.params.arguments ?? {})
  try {
    switch (request.params.name) {
      case "llm_wiki_status": {
        const [health, projects] = await Promise.all([
          client.health(),
          client.projects().catch(() => ({ projects: [], currentProject: null })),
        ])
        return textResult(JSON.stringify({ ...health, ...projects, sessionProject: projectBinding.project }, null, 2))
      }
      case "llm_wiki_projects": {
        await assertMcpEnabled()
        return textResult(JSON.stringify({ ...(await client.projects()), sessionProject: projectBinding.project }, null, 2))
      }
      case "llm_wiki_set_project": {
        await assertMcpEnabled()
        const requested = stringArg(args.project_id, "project_id")
        const projects = await client.projects()
        let pinned: ApiProject
        try {
          pinned = projectBinding.pin(requested, projects.projects, projects.currentProject)
        } catch (error) {
          throw new McpError(ErrorCode.InvalidParams, scopedErrorMessage(error))
        }
        return textResult(JSON.stringify({ activeProject: pinned, pinned: true }, null, 2))
      }
      case "llm_wiki_files": {
        await assertMcpEnabled()
        const scope = await resolveProjectScope(args)
        const response = await client.files(scope.id, {
          root: enumArg(args.root, ["wiki", "sources", "all"] as const, "wiki"),
          recursive: boolArg(args.recursive, true),
          maxFiles: numberArg(args.max_files),
        })
        return textResult(withActiveProject(formatFileTree(response.files, response.truncated), scope.project, scope.id))
      }
      case "llm_wiki_read_file": {
        await assertMcpEnabled()
        const relPath = stringArg(args.path, "path")
        const scope = await resolveProjectScope(args)
        const { path, content } = await client.fileContent(scope.id, relPath)
        return textResult(withActiveProject(`# ${path}\n\n${truncateText(content, MAX_TEXT_BYTES)}`, scope.project, scope.id))
      }
      case "llm_wiki_reviews": {
        await assertMcpEnabled()
        const scope = await resolveProjectScope(args)
        const reviews = await client.reviews(scope.id, {
          status: enumArg(args.status, ["unresolved", "resolved", "all"] as const, "unresolved"),
          type: optionalStringArg(args.type),
          limit: numberArg(args.limit),
        })
        return textResult(withActiveProject(formatReviews(reviews), scope.project, scope.id))
      }
      case "llm_wiki_search": {
        await assertMcpEnabled()
        const query = stringArg(args.query, "query")
        const scope = await resolveProjectScope(args)
        const search = await client.search(scope.id, query, {
          topK: numberArg(args.top_k),
          includeContent: boolArg(args.include_content, false),
        })
        return textResult(withActiveProject(formatSearchResults(query, search), scope.project, scope.id))
      }
      case "llm_wiki_chat": {
        await assertMcpEnabled()
        const message = stringArg(args.message, "message")
        const scope = await resolveProjectScope(args)
        const chat = await client.chat(scope.id, message, {
          sessionId: optionalStringArg(args.session_id),
          mode: enumArg(args.mode, ["fast", "standard", "deep", "local_first"] as const, "standard"),
          topK: numberArg(args.top_k),
          includeContent: boolArg(args.include_content, false),
          wiki: boolArg(args.wiki, true),
          web: boolArg(args.web, false),
          anytxt: boolArg(args.anytxt, false),
          skills: stringArrayArg(args.skills),
          persistSession: optionalStringArg(args.session_id) !== undefined,
        })
        return textResult(withActiveProject(formatChatResponse(chat), scope.project, scope.id))
      }
      case "llm_wiki_graph": {
        await assertMcpEnabled()
        const scope = await resolveProjectScope(args)
        const graph = await client.graph(scope.id, {
          q: optionalStringArg(args.q),
          nodeType: optionalStringArg(args.node_type),
          limit: numberArg(args.limit),
          offset: numberArg(args.offset),
          edgeScope: optionalStringArg(args.edge_scope)
            ? enumArg(args.edge_scope, ["page", "filtered"] as const, "page")
            : (args.offset !== undefined ? "filtered" : "page"),
        })
        return textResult(withActiveProject(formatGraph(graph), scope.project, scope.id))
      }
      case "llm_wiki_rescan_sources": {
        await assertMcpEnabled()
        const scope = await resolveProjectScope(args)
        return textResult(withActiveProject(JSON.stringify(await client.rescan(scope.id), null, 2), scope.project, scope.id))
      }
      case "llm_wiki_embed_page": {
        await assertMcpEnabled()
        const path = stringArg(args.path, "path")
        const scope = await resolveProjectScope(args)
        const result = await client.embedPage(path, scope.id, boolArg(args.force, false))
        return textResult(withActiveProject(JSON.stringify(result, null, 2), scope.project, scope.id))
      }
      case "llm_wiki_write_page": {
        await assertMcpEnabled()
        const path = wikiWritePathArg(args.path)
        const content = writeContentArg(args.content)
        const scope = await resolveProjectScope(args)
        const result = await client.writePage(
          path,
          content,
          scope.id,
          boolArg(args.allow_overwrite, false),
        )
        return textResult(withActiveProject(JSON.stringify(result, null, 2), scope.project, scope.id))
      }
      default:
        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`)
    }
  } catch (err) {
    if (err instanceof McpError) {
      throw new McpError(err.code, scopedErrorMessage(err.message))
    }
    throw new McpError(
      ErrorCode.InternalError,
      scopedErrorMessage(err),
    )
  }
})

async function assertMcpEnabled(): Promise<void> {
  const health = await client.health()
  if (health.mcpEnabled === false) {
    throw new McpError(
      ErrorCode.InvalidRequest,
      "LLM Wiki MCP access is disabled. Enable Settings -> API + MCP -> Enable MCP access in the desktop app.",
    )
  }
}

function textResult(text: string) {
  return {
    content: [{ type: "text" as const, text }],
  }
}

function asObject(value: unknown): Record<string, unknown> {
  if (!value || typeof value !== "object" || Array.isArray(value)) return {}
  return value as Record<string, unknown>
}

async function resolveProjectScope(args: Record<string, unknown>): Promise<{ id: string; project: ApiProject | null }> {
  let id: string
  try {
    id = projectBinding.resolve(optionalStringArg(args.project_id) ?? undefined)
  } catch (error) {
    throw new McpError(ErrorCode.InvalidParams, scopedErrorMessage(error))
  }
  if (projectBinding.project) return { id, project: projectBinding.project }
  const projects = await client.projects()
  const project = id === DEFAULT_PROJECT_ID
    ? projects.currentProject
    : projects.projects.find((candidate) => candidate.id === id || candidate.path === id) ?? null
  return { id, project }
}

function scopedErrorMessage(error: unknown): string {
  const message = error instanceof Error ? error.message : String(error)
  const project = projectBinding.project
  if (!project || message.includes("[activeProject:")) return message
  return `[activeProject: ${project.name} (${project.id})] ${message}`
}

function stringArg(value: unknown, name: string): string {
  if (typeof value !== "string" || value.trim() === "") {
    throw new McpError(ErrorCode.InvalidParams, `${name} is required`)
  }
  return value
}

function wikiWritePathArg(value: unknown): string {
  const path = stringArg(value, "path")
  if (Buffer.byteLength(path, "utf8") > 4_096) {
    throw new McpError(ErrorCode.InvalidParams, "path is too large")
  }
  if (path.includes("\\") || path.startsWith("/") || !path.startsWith("wiki/") || !path.endsWith(".md")) {
    throw new McpError(ErrorCode.InvalidParams, "path must be a canonical Markdown path under wiki/")
  }
  const segments = path.split("/")
  if (segments.some((segment) => !segment || segment === "." || segment === ".." || segment.startsWith("."))) {
    throw new McpError(ErrorCode.InvalidParams, "path contains a noncanonical component")
  }
  return path
}

function writeContentArg(value: unknown): string {
  if (typeof value !== "string") {
    throw new McpError(ErrorCode.InvalidParams, "content is required")
  }
  if (Buffer.byteLength(value, "utf8") > MAX_WRITE_PAGE_BYTES) {
    throw new McpError(ErrorCode.InvalidParams, "content is too large")
  }
  return value
}

function optionalStringArg(value: unknown): string | undefined {
  return typeof value === "string" && value.trim() !== "" ? value : undefined
}

function boolArg(value: unknown, fallback: boolean): boolean {
  return typeof value === "boolean" ? value : fallback
}

function numberArg(value: unknown): number | undefined {
  return typeof value === "number" && Number.isFinite(value) ? value : undefined
}

function enumArg<T extends string>(value: unknown, allowed: readonly T[], fallback: T): T {
  return typeof value === "string" && allowed.includes(value as T) ? value as T : fallback
}

function stringArrayArg(value: unknown): string[] | undefined {
  if (!Array.isArray(value)) return undefined
  return value.filter((item): item is string => typeof item === "string" && item.trim() !== "")
}

function truncateText(value: string, maxBytes: number): string {
  const bytes = Buffer.byteLength(value, "utf8")
  if (bytes <= maxBytes) return value
  let out = ""
  let used = 0
  for (const ch of value) {
    const size = Buffer.byteLength(ch, "utf8")
    if (used + size > maxBytes) break
    out += ch
    used += size
  }
  return `${out}\n\n[truncated: ${bytes - used} bytes omitted]`
}

function formatFileTree(files: ApiFileNode[], truncated = false): string {
  if (files.length === 0) return "No files found."
  const lines: string[] = truncated
    ? ["[warning] File tree was truncated by the LLM Wiki API maxFiles limit.", ""]
    : []
  const walk = (nodes: ApiFileNode[], depth: number) => {
    for (const node of nodes) {
      const prefix = "  ".repeat(depth)
      lines.push(`${prefix}${node.isDir ? "📁" : "📄"} ${node.path}`)
      if (node.children) walk(node.children, depth + 1)
    }
  }
  walk(files, 0)
  return lines.join("\n")
}

function formatSearchResults(query: string, search: { results: ApiSearchResult[]; mode?: string; tokenHits?: number; vectorHits?: number }): string {
  const { results } = search
  if (results.length === 0) return `No results for "${query}".`
  const meta = [
    search.mode ? `Mode: ${search.mode}` : null,
    typeof search.tokenHits === "number" ? `Token hits: ${search.tokenHits}` : null,
    typeof search.vectorHits === "number" ? `Vector hits: ${search.vectorHits}` : null,
  ].filter(Boolean)
  const lines = [`# Search results for "${query}"`, ...(meta.length > 0 ? [meta.join(" | ")] : []), ""]
  results.forEach((result, index) => {
    lines.push(`## ${index + 1}. ${result.title}`)
    lines.push(`Path: ${result.path}`)
    lines.push(`Score: ${result.score.toFixed(6)}${typeof result.vectorScore === "number" ? ` | Vector score: ${result.vectorScore.toFixed(6)}` : ""}`)
    if (result.snippet) lines.push(`Snippet: ${result.snippet}`)
    if (result.images && result.images.length > 0) {
      lines.push(`Images: ${result.images.map((image) => image.url).join(", ")}`)
    }
    lines.push("")
  })
  return lines.join("\n")
}

function formatChatResponse(chat: ApiChatResponse): string {
  const lines = [
    "# LLM Wiki Agent response",
    "",
    `Session: ${chat.sessionId || "(none)"}`,
    chat.mode ? `Mode: ${chat.mode}` : null,
    chat.projectId ? `Project: ${chat.projectId}` : null,
    chat.usage
      ? `Usage: promptChars=${chat.usage.promptChars ?? 0}, completionChars=${chat.usage.completionChars ?? 0}, references=${chat.usage.referenceCount ?? chat.references.length}`
      : null,
    "",
    chat.message.content || "(empty response)",
    "",
  ].filter((line): line is string => line !== null)

  if (chat.references.length > 0) {
    lines.push("## References")
    chat.references.forEach((reference, index) => {
      lines.push(`${index + 1}. ${reference.title || reference.path}`)
      lines.push(`   Kind: ${reference.kind}`)
      lines.push(`   Path: ${reference.path}`)
      if (typeof reference.score === "number") lines.push(`   Score: ${reference.score.toFixed(6)}`)
      if (reference.snippet) lines.push(`   Snippet: ${reference.snippet}`)
    })
    lines.push("")
  }

  if (chat.toolEvents.length > 0) {
    lines.push("## Tool events")
    chat.toolEvents.forEach((event) => {
      lines.push(`- ${event.tool}: ${event.status}${event.detail ? ` (${event.detail})` : ""}`)
    })
  }

  return lines.join("\n")
}

function formatReviews(response: ApiReviewsResponse): string {
  const { reviews } = response
  if (reviews.length === 0) return `No ${response.status} review items found.`
  const lines = [
    "# Review items",
    "",
    `Status: ${response.status}`,
    `Count: ${response.count}`,
    "",
  ]
  reviews.forEach((review, index) => {
    lines.push(`## ${index + 1}. ${review.title || review.id}`)
    lines.push(`ID: ${review.id}`)
    lines.push(`Type: ${review.type}`)
    lines.push(`Resolved: ${review.resolved ? "yes" : "no"}`)
    if (review.sourcePath) lines.push(`Source: ${review.sourcePath}`)
    if (review.affectedPages && review.affectedPages.length > 0) {
      lines.push(`Affected pages: ${review.affectedPages.join(", ")}`)
    }
    if (review.searchQueries && review.searchQueries.length > 0) {
      lines.push(`Search queries: ${review.searchQueries.join(", ")}`)
    }
    if (review.description) lines.push(`Description: ${review.description}`)
    const optionSummary = formatReviewOptions(review)
    if (optionSummary) lines.push(`Options: ${optionSummary}`)
    lines.push("")
  })
  return lines.join("\n")
}

function formatReviewOptions(review: ApiReviewItem): string {
  if (!review.options || review.options.length === 0) return ""
  return review.options
    .map((option) => option.label ? `${option.label} (${option.action})` : option.action)
    .join(", ")
}

function formatGraph(graph: { nodes: ApiGraphNode[]; edges: Array<{ source: string; target: string; weight?: number }>; offset: number; totalCount: number; hasMore: boolean }): string {
  const { nodes, edges } = graph
  const typeCounts = new Map<string, number>()
  for (const node of nodes) typeCounts.set(node.type, (typeCounts.get(node.type) ?? 0) + 1)
  const lines = [
    "# Knowledge graph",
    "",
    `Nodes: ${nodes.length}`,
    `Edges: ${edges.length}`,
    `Page: offset ${graph.offset}, ${nodes.length} of ${graph.totalCount}${graph.hasMore ? " (more available)" : ""}`,
    "",
    "## Node types",
    ...[...typeCounts.entries()]
      .sort((a, b) => b[1] - a[1])
      .map(([type, count]) => `- ${type}: ${count}`),
    "",
    "## Top nodes",
    ...nodes
      .slice()
      .sort((a, b) => (b.linkCount ?? 0) - (a.linkCount ?? 0))
      .slice(0, 30)
      .map((node) => `- ${node.label} (${node.type}, ${node.linkCount ?? 0} links)${node.path ? ` — ${node.path}` : ""}`),
  ]
  return lines.join("\n")
}

async function main(): Promise<void> {
  const transport = new StdioServerTransport()
  await server.connect(transport)
  console.error(`LLM Wiki MCP server v${VERSION} connected to ${process.env.LLM_WIKI_API_BASE_URL ?? "http://127.0.0.1:19828"}`)
}

main().catch((err) => {
  console.error("Failed to start LLM Wiki MCP server:", err)
  process.exit(1)
})