codewiki-mcp 1.0.0 → 1.1.0

package/src/lib/codewikiClient.ts

@@ -1,294 +0,0 @@
-import type { CodeWikiConfig } from './config.js'
-import { extractRpcPayload } from './batchexecute.js'
-import { CodeWikiError } from './errors.js'
-import { normalizeRepoInput } from './repo.js'
-
-export interface CodeWikiClientOptions {
-  baseUrl?: string
-  timeoutMs?: number
-  maxRetries?: number
-  retryDelay?: number
-}
-
-export interface SearchRepoResult {
-  fullName: string
-  url: string | null
-  description: string | null
-  avatarUrl: string | null
-  extraScore: number | null
-  raw: unknown
-}
-
-export interface WikiSection {
-  title: string
-  level: number
-  summary: string | null
-  markdown: string
-  anchor: string | null
-  diagramCount: number
-  raw: unknown
-}
-
-export interface FetchRepositoryResult {
-  repo: string
-  commit: string | null
-  canonicalUrl: string | null
-  sections: WikiSection[]
-  raw: unknown
-}
-
-export interface AskHistoryItem {
-  role: 'user' | 'assistant'
-  content: string
-}
-
-export interface ResponseMeta {
-  totalBytes: number
-  totalElapsedMs: number
-}
-
-export interface WithMeta<T> {
-  data: T
-  meta: ResponseMeta
-}
-
-export class CodeWikiClient {
-  private readonly baseUrl: string
-  private readonly timeoutMs: number
-  private readonly maxRetries: number
-  private readonly retryDelay: number
-
-  constructor(options: CodeWikiClientOptions = {}) {
-    this.baseUrl = options.baseUrl ?? 'https://codewiki.google'
-    this.timeoutMs = options.timeoutMs ?? 30_000
-    this.maxRetries = options.maxRetries ?? 3
-    this.retryDelay = options.retryDelay ?? 250
-  }
-
-  static fromConfig(config: CodeWikiConfig): CodeWikiClient {
-    return new CodeWikiClient({
-      baseUrl: config.baseUrl,
-      timeoutMs: config.requestTimeout,
-      maxRetries: config.maxRetries,
-      retryDelay: config.retryDelay,
-    })
-  }
-
-  async searchRepositories(query: string, limit = 10): Promise<WithMeta<SearchRepoResult[]>> {
-    const start = performance.now()
-    const { payload, bytes } = await this.callRpc('vyWDAf', [query, limit, query, 0], { sourcePath: '/' })
-
-    const rows = Array.isArray(payload) && Array.isArray(payload[0])
-      ? payload[0]
-      : []
-
-    const data = rows
-      .filter((item): item is unknown[] => Array.isArray(item))
-      .map((item) => {
-        const fullName = typeof item[0] === 'string' ? item[0] : 'unknown/unknown'
-        const url = Array.isArray(item[3]) && typeof item[3][1] === 'string' ? item[3][1] : null
-
-        let description: string | null = null
-        let avatarUrl: string | null = null
-        let extraScore: number | null = null
-        if (Array.isArray(item[5])) {
-          description = typeof item[5][0] === 'string' ? item[5][0] : null
-          avatarUrl = typeof item[5][1] === 'string' ? item[5][1] : null
-          extraScore = typeof item[5][2] === 'number' ? item[5][2] : null
-        }
-
-        return {
-          fullName,
-          url,
-          description,
-          avatarUrl,
-          extraScore,
-          raw: item,
-        }
-      })
-
-    return {
-      data,
-      meta: { totalBytes: bytes, totalElapsedMs: Math.round(performance.now() - start) },
-    }
-  }
-
-  async fetchRepository(repoInput: string): Promise<WithMeta<FetchRepositoryResult>> {
-    const start = performance.now()
-    const repo = normalizeRepoInput(repoInput)
-
-    const { payload, bytes } = await this.callRpc('VSX6ub', [repo.repoUrl], {
-      sourcePath: repo.sourcePath,
-    })
-
-    const root = Array.isArray(payload) ? payload : []
-    const primary = Array.isArray(root[0]) ? root[0] : []
-    const repoInfo = Array.isArray(primary[0]) ? primary[0] : []
-    const sectionsRaw = Array.isArray(primary[1]) ? primary[1] : []
-
-    const canonicalUrl =
-      Array.isArray(root[1])
-      && Array.isArray(root[1][0])
-      && typeof root[1][0][1] === 'string'
-        ? root[1][0][1]
-        : null
-
-    const repoName = typeof repoInfo[0] === 'string' ? repoInfo[0] : repo.repoPath
-    const commit = typeof repoInfo[1] === 'string' ? repoInfo[1] : null
-
-    const sections: WikiSection[] = sectionsRaw
-      .filter((item): item is unknown[] => Array.isArray(item))
-      .map((item) => {
-        const title = typeof item[0] === 'string' ? item[0] : 'Untitled'
-
-        const rawLevel = item[1]
-        const level = typeof rawLevel === 'number' && Number.isFinite(rawLevel)
-          ? Math.max(1, Math.min(6, Math.floor(rawLevel)))
-          : 1
-
-        const summary = typeof item[2] === 'string' ? item[2] : null
-        const markdown = typeof item[5] === 'string'
-          ? item[5]
-          : typeof item[4] === 'string'
-            ? item[4]
-            : (summary ?? '')
-
-        let diagramCount = 0
-        if (Array.isArray(item[7])) {
-          diagramCount = item[7].length
-        }
-
-        const anchor = [...item]
-          .reverse()
-          .find((value): value is string => typeof value === 'string' && value.startsWith('#')) ?? null
-
-        return {
-          title,
-          level,
-          summary,
-          markdown,
-          anchor,
-          diagramCount,
-          raw: item,
-        }
-      })
-
-    return {
-      data: {
-        repo: repoName,
-        commit,
-        canonicalUrl,
-        sections,
-        raw: payload,
-      },
-      meta: { totalBytes: bytes, totalElapsedMs: Math.round(performance.now() - start) },
-    }
-  }
-
-  async askRepository(repoInput: string, question: string, history: AskHistoryItem[] = []): Promise<WithMeta<string>> {
-    const start = performance.now()
-    const repo = normalizeRepoInput(repoInput)
-
-    const messages: [string, 'user' | 'model'][] = [
-      ...history.map(item => [item.content, item.role === 'assistant' ? 'model' : 'user'] as [string, 'user' | 'model']),
-      [question, 'user'],
-    ]
-
-    const { payload, bytes } = await this.callRpc('EgIxfe', [messages, [null, repo.repoUrl]], {
-      sourcePath: repo.sourcePath,
-    })
-
-    let data: string
-    if (Array.isArray(payload) && typeof payload[0] === 'string') {
-      data = payload[0]
-    } else if (typeof payload === 'string') {
-      data = payload
-    } else {
-      data = JSON.stringify(payload, null, 2)
-    }
-
-    return {
-      data,
-      meta: { totalBytes: bytes, totalElapsedMs: Math.round(performance.now() - start) },
-    }
-  }
-
-  private async callRpc(
-    rpcId: string,
-    rpcPayload: unknown,
-    options: { sourcePath?: string } = {},
-  ): Promise<{ payload: unknown; bytes: number }> {
-    const url = new URL(`${this.baseUrl}/_/BoqAngularSdlcAgentsUi/data/batchexecute`)
-    url.searchParams.set('rpcids', rpcId)
-    url.searchParams.set('rt', 'c')
-
-    if (options.sourcePath) {
-      url.searchParams.set('source-path', options.sourcePath)
-    }
-
-    const bodyObject = [[[rpcId, JSON.stringify(rpcPayload), null, 'generic']]]
-    const body = `f.req=${encodeURIComponent(JSON.stringify(bodyObject))}&`
-
-    let lastError: unknown
-
-    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-      if (attempt > 0) {
-        const delay = this.retryDelay * Math.pow(2, attempt - 1)
-        await new Promise(resolve => setTimeout(resolve, delay))
-      }
-
-      const abortController = new AbortController()
-      const timeout = setTimeout(() => abortController.abort(), this.timeoutMs)
-
-      try {
-        const response = await fetch(url, {
-          method: 'POST',
-          headers: {
-            'content-type': 'application/x-www-form-urlencoded;charset=UTF-8',
-          },
-          body,
-          signal: abortController.signal,
-        })
-
-        if (!response.ok) {
-          throw new CodeWikiError('RPC_FAIL', `CodeWiki RPC ${rpcId} failed with status ${response.status}`, {
-            statusCode: response.status,
-            rpcId,
-          })
-        }
-
-        const text = await response.text()
-        const bytes = Buffer.byteLength(text, 'utf8')
-        const payload = extractRpcPayload(text, rpcId)
-        return { payload, bytes }
-      } catch (err) {
-        lastError = err
-
-        if (err instanceof CodeWikiError && err.code === 'RPC_FAIL' && err.statusCode && err.statusCode < 500) {
-          throw err
-        }
-
-        if (err instanceof DOMException && err.name === 'AbortError') {
-          lastError = new CodeWikiError('TIMEOUT', `CodeWiki RPC ${rpcId} timed out after ${this.timeoutMs}ms`, {
-            rpcId,
-            cause: err,
-          })
-          if (attempt === this.maxRetries) throw lastError
-          continue
-        }
-
-        if (attempt === this.maxRetries) {
-          if (err instanceof CodeWikiError) throw err
-          throw new CodeWikiError('RPC_FAIL', `CodeWiki RPC ${rpcId} failed: ${err instanceof Error ? err.message : String(err)}`, {
-            rpcId,
-            cause: err,
-          })
-        }
-      } finally {
-        clearTimeout(timeout)
-      }
-    }
-
-    throw lastError
-  }
-}

package/src/lib/config.ts

@@ -1,30 +0,0 @@
-export interface CodeWikiConfig {
-  baseUrl: string
-  requestTimeout: number
-  maxRetries: number
-  retryDelay: number
-  githubToken?: string
-}
-
-const defaults: CodeWikiConfig = {
-  baseUrl: 'https://codewiki.google',
-  requestTimeout: 30_000,
-  maxRetries: 3,
-  retryDelay: 250,
-}
-
-export function loadConfig(env: Record<string, string | undefined> = process.env): CodeWikiConfig {
-  return {
-    baseUrl: env.CODEWIKI_BASE_URL ?? defaults.baseUrl,
-    requestTimeout: parsePositiveInt(env.CODEWIKI_REQUEST_TIMEOUT, defaults.requestTimeout),
-    maxRetries: parsePositiveInt(env.CODEWIKI_MAX_RETRIES, defaults.maxRetries),
-    retryDelay: parsePositiveInt(env.CODEWIKI_RETRY_DELAY, defaults.retryDelay),
-    githubToken: env.GITHUB_TOKEN || undefined,
-  }
-}
-
-function parsePositiveInt(value: string | undefined, fallback: number): number {
-  if (value === undefined) return fallback
-  const n = Number.parseInt(value, 10)
-  return Number.isFinite(n) && n > 0 ? n : fallback
-}

package/src/lib/errors.ts

@@ -1,57 +0,0 @@
-export type ErrorCode = 'VALIDATION' | 'RPC_FAIL' | 'TIMEOUT' | 'NLP_RESOLVE_FAIL'
-
-export class CodeWikiError extends Error {
-  readonly code: ErrorCode
-  readonly statusCode: number | undefined
-  readonly rpcId: string | undefined
-
-  constructor(
-    code: ErrorCode,
-    message: string,
-    options?: { statusCode?: number; rpcId?: string; cause?: unknown },
-  ) {
-    super(message, { cause: options?.cause })
-    this.name = 'CodeWikiError'
-    this.code = code
-    this.statusCode = options?.statusCode
-    this.rpcId = options?.rpcId
-  }
-}
-
-export interface ErrorEnvelope {
-  error: {
-    code: ErrorCode
-    message: string
-    rpcId?: string
-    statusCode?: number
-  }
-}
-
-export function formatMcpError(err: unknown): { content: { type: 'text'; text: string }[]; isError: true } {
-  if (err instanceof CodeWikiError) {
-    const envelope: ErrorEnvelope = {
-      error: {
-        code: err.code,
-        message: err.message,
-        ...(err.rpcId ? { rpcId: err.rpcId } : {}),
-        ...(err.statusCode ? { statusCode: err.statusCode } : {}),
-      },
-    }
-    return {
-      content: [{ type: 'text', text: JSON.stringify(envelope, null, 2) }],
-      isError: true,
-    }
-  }
-
-  const message = err instanceof Error ? err.message : String(err)
-  const envelope: ErrorEnvelope = {
-    error: {
-      code: 'RPC_FAIL',
-      message,
-    },
-  }
-  return {
-    content: [{ type: 'text', text: JSON.stringify(envelope, null, 2) }],
-    isError: true,
-  }
-}

package/src/lib/extractKeyword.ts

@@ -1,47 +0,0 @@
-import winkNLP from 'wink-nlp'
-import model from 'wink-eng-lite-web-model'
-
-const nlp = winkNLP(model)
-const its = nlp.its
-
-const STOP_WORDS = new Set([
-  'repo', 'repository', 'library', 'framework', 'package', 'module',
-  'project', 'tool', 'code', 'source', 'open', 'github', 'gitlab',
-  'the', 'a', 'an', 'this', 'that', 'about', 'for', 'with', 'from',
-  'how', 'what', 'where', 'which', 'who', 'when', 'why', 'does',
-  'show', 'tell', 'me', 'find', 'search', 'get', 'fetch', 'look',
-  'please', 'can', 'could', 'would', 'should', 'use', 'using',
-  'is', 'are', 'was', 'were', 'be', 'been', 'being',
-  'have', 'has', 'had', 'do', 'did', 'will', 'shall',
-  'of', 'in', 'to', 'on', 'at', 'by', 'up', 'it', 'its',
-])
-
-const SKIP_POS = new Set(['PUNCT', 'SPACE', 'DET', 'ADP', 'CCONJ', 'SCONJ', 'AUX', 'PART', 'INTJ'])
-
-export function extractKeyword(text: string): string | null {
-  const doc = nlp.readDoc(text)
-  const tokens = doc.tokens()
-
-  // First pass: look for NOUN/PROPN that aren't stop words
-  const nouns: string[] = []
-  const fallback: string[] = []
-
-  tokens.each((token: any) => {
-    const pos = token.out(its.pos) as string
-    const value = token.out(its.value) as string
-    const lower = value.toLowerCase()
-
-    if (SKIP_POS.has(pos) || value.length <= 1) return
-
-    if (!STOP_WORDS.has(lower)) {
-      if (pos === 'NOUN' || pos === 'PROPN') {
-        nouns.push(value)
-      } else {
-        fallback.push(value)
-      }
-    }
-  })
-
-  // Prefer nouns, then fall back to any non-stop-word token
-  return nouns[0] ?? fallback[0] ?? null
-}

package/src/lib/repo.ts

@@ -1,70 +0,0 @@
-import type { CodeWikiConfig } from './config.js'
-import { extractKeyword } from './extractKeyword.js'
-import { resolveRepoFromGitHub } from './resolveRepo.js'
-
-export interface NormalizedRepo {
-  host: string
-  repoPath: string
-  repoUrl: string
-  sourcePath: string
-}
-
-export function normalizeRepoInput(input: string): NormalizedRepo {
-  const raw = input.trim()
-  if (!raw) {
-    throw new Error('Repository input is empty')
-  }
-
-  if (/^https?:\/\//i.test(raw)) {
-    const url = new URL(raw)
-    const repoPath = url.pathname.replace(/^\/+|\/+$/g, '')
-    const parts = repoPath.split('/').filter(Boolean)
-    if (parts.length < 2) {
-      throw new Error('Expected repository URL in the format https://host/owner/repo')
-    }
-
-    const normalizedPath = `${parts[0]}/${parts[1]}`
-    return {
-      host: url.hostname,
-      repoPath: normalizedPath,
-      repoUrl: `https://${url.hostname}/${normalizedPath}`,
-      sourcePath: `/${url.hostname}/${normalizedPath}`,
-    }
-  }
-
-  const parts = raw.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean)
-  if (parts.length !== 2) {
-    throw new Error('Expected repository in owner/repo format or full URL')
-  }
-
-  const repoPath = `${parts[0]}/${parts[1]}`
-  return {
-    host: 'github.com',
-    repoPath,
-    repoUrl: `https://github.com/${repoPath}`,
-    sourcePath: `/github.com/${repoPath}`,
-  }
-}
-
-export async function resolveRepoInput(
-  input: string,
-  config?: Pick<CodeWikiConfig, 'githubToken' | 'requestTimeout'>,
-): Promise<NormalizedRepo> {
-  const raw = input.trim()
-
-  // URL → sync
-  if (/^https?:\/\//i.test(raw)) {
-    return normalizeRepoInput(raw)
-  }
-
-  // owner/repo → sync
-  const parts = raw.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean)
-  if (parts.length === 2) {
-    return normalizeRepoInput(raw)
-  }
-
-  // Natural language → NLP → GitHub search → normalize
-  const keyword = extractKeyword(raw) ?? raw
-  const fullName = await resolveRepoFromGitHub(keyword, config ?? { requestTimeout: 30_000 })
-  return normalizeRepoInput(fullName)
-}

package/src/lib/resolveRepo.ts

@@ -1,60 +0,0 @@
-import type { CodeWikiConfig } from './config.js'
-import { CodeWikiError } from './errors.js'
-
-interface GitHubSearchItem {
-  full_name: string
-}
-
-interface GitHubSearchResponse {
-  items?: GitHubSearchItem[]
-}
-
-export async function resolveRepoFromGitHub(
-  keyword: string,
-  config: Pick<CodeWikiConfig, 'githubToken' | 'requestTimeout'>,
-): Promise<string> {
-  const url = new URL('https://api.github.com/search/repositories')
-  url.searchParams.set('q', keyword)
-  url.searchParams.set('sort', 'stars')
-  url.searchParams.set('per_page', '1')
-
-  const headers: Record<string, string> = {
-    'Accept': 'application/vnd.github+json',
-    'User-Agent': 'codewiki-mcp',
-  }
-  if (config.githubToken) {
-    headers['Authorization'] = `Bearer ${config.githubToken}`
-  }
-
-  const abortController = new AbortController()
-  const timeout = setTimeout(() => abortController.abort(), config.requestTimeout)
-
-  try {
-    const response = await fetch(url, {
-      headers,
-      signal: abortController.signal,
-    })
-
-    if (!response.ok) {
-      throw new CodeWikiError('NLP_RESOLVE_FAIL', `GitHub search failed with status ${response.status}`, {
-        statusCode: response.status,
-      })
-    }
-
-    const body = await response.json() as GitHubSearchResponse
-    const firstItem = body.items?.[0]
-
-    if (!firstItem) {
-      throw new CodeWikiError('NLP_RESOLVE_FAIL', `No GitHub repository found for "${keyword}"`)
-    }
-
-    return firstItem.full_name
-  } catch (err) {
-    if (err instanceof CodeWikiError) throw err
-    throw new CodeWikiError('NLP_RESOLVE_FAIL', `Failed to resolve "${keyword}": ${err instanceof Error ? err.message : String(err)}`, {
-      cause: err,
-    })
-  } finally {
-    clearTimeout(timeout)
-  }
-}

package/src/schemas.ts

@@ -1,22 +0,0 @@
-import { z } from 'zod'
-
-export type { ErrorEnvelope } from './lib/errors.js'
-
-export const SearchReposInput = z.object({
-  query: z.string().min(1),
-  limit: z.number().int().min(1).max(50).default(10),
-})
-
-export const FetchRepoInput = z.object({
-  repo: z.string().min(1),
-  mode: z.enum(['aggregate', 'pages']).default('aggregate'),
-})
-
-export const AskRepoInput = z.object({
-  repo: z.string().min(1),
-  question: z.string().min(1),
-  history: z.array(z.object({
-    role: z.enum(['user', 'assistant']),
-    content: z.string().min(1),
-  })).max(20).optional(),
-})

package/src/server.ts

@@ -1,120 +0,0 @@
-import { createServer, type Server } from 'node:http'
-import { randomUUID } from 'node:crypto'
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
-import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'
-import type { CodeWikiConfig } from './lib/config.js'
-import { CodeWikiClient } from './lib/codewikiClient.js'
-import { registerSearchReposTool } from './tools/searchRepos.js'
-import { registerFetchRepoTool } from './tools/fetchRepo.js'
-import { registerAskRepoTool } from './tools/askRepo.js'
-
-export interface ServerOptions {
-  transport: 'stdio' | 'http' | 'sse'
-  port?: number
-  endpoint?: string
-}
-
-const VERSION = '0.2.0'
-
-export function createMcpServer(config: CodeWikiConfig): McpServer {
-  const mcp = new McpServer({
-    name: 'codewiki-mcp',
-    version: VERSION,
-  })
-
-  const client = CodeWikiClient.fromConfig(config)
-
-  registerSearchReposTool(mcp, client)
-  registerFetchRepoTool(mcp, client, config)
-  registerAskRepoTool(mcp, client, config)
-
-  return mcp
-}
-
-let httpServer: Server | undefined
-
-export async function startServer(mcp: McpServer, options: ServerOptions): Promise<void> {
-  const { transport, port = 3000, endpoint = '/mcp' } = options
-
-  if (transport === 'stdio') {
-    const stdioTransport = new StdioServerTransport()
-    await mcp.connect(stdioTransport)
-    return
-  }
-
-  if (transport === 'http') {
-    const httpTransport = new StreamableHTTPServerTransport({
-      sessionIdGenerator: () => randomUUID(),
-    })
-
-    httpServer = createServer(async (req, res) => {
-      if (req.url === endpoint) {
-        await httpTransport.handleRequest(req, res)
-      } else {
-        res.writeHead(404).end('Not Found')
-      }
-    })
-
-    await mcp.connect(httpTransport)
-
-    await new Promise<void>((resolve) => {
-      httpServer!.listen(port, () => {
-        console.error(`codewiki-mcp HTTP server listening on http://localhost:${port}${endpoint}`)
-        resolve()
-      })
-    })
-    return
-  }
-
-  if (transport === 'sse') {
-    const sessions = new Map<string, SSEServerTransport>()
-
-    httpServer = createServer(async (req, res) => {
-      const url = new URL(req.url ?? '/', `http://localhost:${port}`)
-
-      if (url.pathname === endpoint && req.method === 'GET') {
-        const sseTransport = new SSEServerTransport(`${endpoint}/message`, res)
-        sessions.set(sseTransport.sessionId, sseTransport)
-
-        sseTransport.onclose = () => {
-          sessions.delete(sseTransport.sessionId)
-        }
-
-        await mcp.connect(sseTransport)
-        return
-      }
-
-      if (url.pathname === `${endpoint}/message` && req.method === 'POST') {
-        const sessionId = url.searchParams.get('sessionId')
-        const sseTransport = sessionId ? sessions.get(sessionId) : undefined
-        if (!sseTransport) {
-          res.writeHead(400).end('Invalid or missing sessionId')
-          return
-        }
-        await sseTransport.handlePostMessage(req, res)
-        return
-      }
-
-      res.writeHead(404).end('Not Found')
-    })
-
-    await new Promise<void>((resolve) => {
-      httpServer!.listen(port, () => {
-        console.error(`codewiki-mcp SSE server listening on http://localhost:${port}${endpoint}`)
-        resolve()
-      })
-    })
-    return
-  }
-}
-
-export async function stopServer(): Promise<void> {
-  if (httpServer) {
-    await new Promise<void>((resolve, reject) => {
-      httpServer!.close((err) => (err ? reject(err) : resolve()))
-    })
-    httpServer = undefined
-  }
-}