@sanqianx/project-knowledge 4.6.1

package/bin/project-knowledge-integrations.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+const {
+  IntegrationManager,
+  SUPPORTED_CLIENTS,
+  normalizeClient,
+} = require('../_site/lib/integration-installer');
+
+function printHelp() {
+  console.log(`project-knowledge-integrations
+
+Install Project Knowledge for coding agents: Knowledge Integration (MCP +
+Skill / plugin) and Development Capture (Bridge hooks / notify / plugin).
+
+Usage:
+  project-knowledge-integrations install [--ide <client>] [--scope <scope>] [--knowledge-only|--capture-only]
+  project-knowledge-integrations update [--ide <client>] [--scope <scope>]
+  project-knowledge-integrations uninstall [--ide <client>] [--scope <scope>] [--knowledge-only|--capture-only]
+  project-knowledge-integrations status [--ide <client>]
+  project-knowledge-integrations disable-capture
+
+Clients:
+  claude       Claude Code plugin (MCP + Skill) + managed Bridge hooks
+  opencode     OpenCode MCP + global Skill + managed Bridge plugin
+  codex        Codex plugin (MCP + Skill) + managed Bridge notify
+  all          All supported clients
+
+Options:
+      --ide <client>       Repeat or use a comma-separated list
+      --scope <scope>      Claude scope: user, project, or local (default: user)
+      --marketplace <src>  Marketplace GitHub repo, Git URL, or local path
+      --knowledge-only     Only install/uninstall the Knowledge Integration
+      --capture-only       Only install/uninstall the Development Capture
+      --dry-run            Show intended operations without changing config
+      --json               Print machine-readable results
+  -h, --help               Show this help
+
+Without --ide, installed clients are detected automatically. One install
+action configures both capabilities; no client UI needs to be opened.`);
+}
+
+function parseArgs(argv) {
+  const operation = argv[0] && !argv[0].startsWith('-') ? argv[0] : 'status';
+  const start = operation === 'status' && (!argv[0] || argv[0].startsWith('-')) ? 0 : 1;
+  const options = {
+    operation,
+    clients: [],
+    scope: 'user',
+    dryRun: false,
+    json: false,
+    help: false,
+    marketplaceSource: '',
+    knowledgeOnly: false,
+    captureOnly: false,
+  };
+  for (let i = start; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--ide' && argv[i + 1]) {
+      options.clients.push(...argv[++i].split(',').filter(Boolean));
+    } else if (arg === '--all') {
+      options.clients.push('all');
+    } else if (arg === '--scope' && argv[i + 1]) {
+      options.scope = argv[++i];
+    } else if (arg === '--marketplace' && argv[i + 1]) {
+      options.marketplaceSource = argv[++i];
+    } else if (arg === '--knowledge-only') {
+      options.knowledgeOnly = true;
+    } else if (arg === '--capture-only') {
+      options.captureOnly = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--json') {
+      options.json = true;
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else {
+      throw new Error(`unknown option: ${arg}`);
+    }
+  }
+  if (options.knowledgeOnly && options.captureOnly) {
+    throw new Error('--knowledge-only and --capture-only are mutually exclusive');
+  }
+  if (!['install', 'update', 'uninstall', 'status', 'disable-capture'].includes(options.operation)) {
+    throw new Error(`unknown operation: ${options.operation}`);
+  }
+  if (!['user', 'project', 'local'].includes(options.scope)) {
+    throw new Error(`unsupported scope: ${options.scope}`);
+  }
+  return options;
+}
+
+function selectClients(requested, manager) {
+  if (requested.some(item => String(item).toLowerCase() === 'all')) return [...SUPPORTED_CLIENTS];
+  if (requested.length) return [...new Set(requested.map(normalizeClient))];
+  const detected = manager.detectClients();
+  if (detected.length) return detected;
+  return [...SUPPORTED_CLIENTS];
+}
+
+function printCapabilityLine(prefix, capability) {
+  if (!capability) return;
+  const mark = capability.ok ? 'OK' : 'FAIL';
+  console.log(`  [${mark}] ${prefix}: ${capability.state} - ${capability.detail}`);
+}
+
+async function runCli(argv = process.argv.slice(2), dependencies = {}) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    printHelp();
+    return 0;
+  }
+  const manager = dependencies.manager || new IntegrationManager({
+    dryRun: options.dryRun,
+    marketplaceSource: options.marketplaceSource || undefined,
+  });
+  const clients = selectClients(options.clients, manager);
+
+  if (options.operation === 'disable-capture') {
+    const summary = await manager.disableAllCapture({ clients });
+    if (options.json) {
+      console.log(JSON.stringify({ operation: 'disable-capture', ...summary, planned: manager.planned }, null, 2));
+    } else {
+      for (const result of summary.clients) {
+        const mark = result.ok ? 'OK' : 'FAIL';
+        console.log(`[${mark}] ${result.label}: ${result.state} - ${result.detail}`);
+      }
+      const consumerMark = summary.consumer.ok ? 'OK' : 'FAIL';
+      console.log(`[${consumerMark}] Bridge consumer: ${summary.consumer.state || summary.consumer.detail}`);
+    }
+    return summary.clients.some(result => !result.ok) || !summary.consumer.ok ? 1 : 0;
+  }
+
+  if (options.operation === 'install') {
+    // One action configures Knowledge Integration + Development Capture
+    // together (per-client flags narrow the scope). No client UI is needed.
+    const summary = await manager.installAll({ clients, knowledgeOnly: options.knowledgeOnly, captureOnly: options.captureOnly, scope: options.scope });
+    if (options.json) {
+      console.log(JSON.stringify({ operation: 'install', ...summary, planned: manager.planned }, null, 2));
+    } else {
+      const bridgeMark = summary.bridge.ok ? 'OK' : 'FAIL';
+      console.log(`[${bridgeMark}] Bridge: ${summary.bridge.state} - consumer ${manager.bridgeConsumerName}`);
+      for (const entry of summary.clients) {
+        printCapabilityLine(`${entry.label} Knowledge Integration`, entry.knowledgeIntegration);
+        printCapabilityLine(`${entry.label} Development Capture`, entry.developmentCapture);
+      }
+      if (options.dryRun && manager.planned.length) {
+        console.log('\nPlanned operations:');
+        for (const item of manager.planned) {
+          if (item.command) console.log(`  ${item.command} ${item.args.join(' ')}`);
+          else if (item.copy) console.log(`  copy ${item.copy} -> ${item.destination}`);
+          else console.log(`  remove ${item.removeConfig} and ${item.removeDirectory}`);
+        }
+      }
+    }
+    return summary.clients.some(entry =>
+      (entry.knowledgeIntegration && !entry.knowledgeIntegration.ok)
+      || (entry.developmentCapture && !entry.developmentCapture.ok)
+    ) || !summary.bridge.ok ? 1 : 0;
+  }
+
+  if (options.operation === 'uninstall') {
+    if (options.captureOnly) {
+      const results = await manager.operateCapture('uninstall', clients, {});
+      if (options.json) {
+        console.log(JSON.stringify({ operation: 'uninstall', captureOnly: true, results, planned: manager.planned }, null, 2));
+      } else {
+        for (const result of results) {
+          const mark = result.ok ? 'OK' : 'FAIL';
+          console.log(`[${mark}] ${result.label}: ${result.state} - ${result.detail}`);
+        }
+      }
+      return results.some(result => !result.ok) ? 1 : 0;
+    }
+    // Default uninstall removes both capabilities but KEEPS the host Bridge
+    // consumer; use disable-capture for the global consumer unregister.
+    const knowledgeResults = await manager.operate('uninstall', clients, { scope: options.scope });
+    const captureResults = options.knowledgeOnly ? [] : await manager.operateCapture('uninstall', clients, {});
+    if (options.json) {
+      console.log(JSON.stringify({ operation: 'uninstall', knowledgeResults, captureResults, planned: manager.planned }, null, 2));
+    } else {
+      for (const result of [...knowledgeResults, ...captureResults]) {
+        const mark = result.ok ? 'OK' : 'FAIL';
+        console.log(`[${mark}] ${result.label}: ${result.state} - ${result.detail}`);
+      }
+    }
+    return [...knowledgeResults, ...captureResults].some(result => !result.ok) ? 1 : 0;
+  }
+
+  if (options.operation === 'status') {
+    const summary = await manager.statusAll({ clients });
+    if (options.json) {
+      console.log(JSON.stringify({ operation: 'status', ...summary, planned: manager.planned }, null, 2));
+    } else {
+      const bridgeMark = summary.bridge.ok ? 'OK' : 'FAIL';
+      console.log(`[${bridgeMark}] Bridge: consumer ${summary.bridge.consumerRegistered ? 'registered' : 'not registered'}, journal ${summary.bridge.bridgeHealthy ? 'healthy' : 'unavailable'}`);
+      for (const entry of summary.clients) {
+        printCapabilityLine(`${entry.label} Knowledge Integration`, entry.knowledgeIntegration);
+        printCapabilityLine(`${entry.label} Development Capture`, entry.developmentCapture);
+      }
+    }
+    return 0;
+  }
+
+  const results = await manager.operate(options.operation, clients, { scope: options.scope });
+  if (options.json) {
+    console.log(JSON.stringify({
+      operation: options.operation,
+      results,
+      planned: manager.planned,
+    }, null, 2));
+  } else {
+    for (const result of results) {
+      const mark = result.ok ? 'OK' : 'FAIL';
+      console.log(`[${mark}] ${result.label}: ${result.state} - ${result.detail}`);
+    }
+    if (options.dryRun && manager.planned.length) {
+      console.log('\nPlanned operations:');
+      for (const item of manager.planned) {
+        if (item.command) console.log(`  ${item.command} ${item.args.join(' ')}`);
+        else if (item.copy) console.log(`  copy ${item.copy} -> ${item.destination}`);
+        else console.log(`  remove ${item.removeConfig} and ${item.removeDirectory}`);
+      }
+    }
+  }
+  return results.some(result => !result.ok) ? 1 : 0;
+}
+
+if (require.main === module) {
+  runCli().then(code => {
+    process.exitCode = code;
+  }).catch(error => {
+    console.error(`project-knowledge-integrations: ${error.message}`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  parseArgs,
+  runCli,
+  selectClients,
+};

package/bin/project-knowledge-kb.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+const { KnowledgeToolRuntime } = require('../_site/lib/knowledge-tool-runtime');
+const { serializeErrorEnvelope, createId } = require('../_site/lib/contracts');
+
+function parseOptions(args) {
+  const first = args[0] || 'help';
+  const output = { command: first === '--help' || first === '-h' ? 'help' : first };
+  for (let index = 1; index < args.length; index += 1) {
+    const key = args[index];
+    if (!key.startsWith('--')) continue;
+    const name = key.slice(2).replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
+    if (args[index + 1] && !args[index + 1].startsWith('--')) output[name] = args[++index];
+    else output[name] = true;
+  }
+  return output;
+}
+
+function help() {
+  process.stdout.write(`project-knowledge-kb
+
+Read-only local knowledge tools:
+  project-knowledge-kb search  --project <projectId-or-legacy-slug> --query <text> [--limit 8]
+  project-knowledge-kb ask     --project <projectId-or-legacy-slug> --query <text> [--limit 8]
+  project-knowledge-kb get     --project <projectId-or-legacy-slug> --entry <path>
+  project-knowledge-kb history --project <projectId-or-legacy-slug> [--limit 20]
+
+Add --json for machine-readable output. These commands never modify knowledge or project configuration.\n`);
+}
+
+async function main(argv = process.argv.slice(2), options = {}) {
+  const args = parseOptions(argv);
+  if (args.command === 'help' || args.help) {
+    help();
+    return 0;
+  }
+  if (!['search', 'ask', 'get', 'history'].includes(args.command)) throw new Error(`unknown command: ${args.command}`);
+  if (!args.project) throw new Error('--project is required');
+  const runtime = options.runtime || new KnowledgeToolRuntime(options);
+  try {
+    const input = { project: args.project, query: args.query, limit: args.limit, entry: args.entry };
+    let result;
+    if (args.command === 'search') result = await runtime.search(input);
+    else if (args.command === 'ask') result = await runtime.ask(input);
+    else if (args.command === 'get') result = await runtime.get(input);
+    else result = await runtime.history(input);
+    if (args.json || args.command !== 'ask') process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    else process.stdout.write(`${result.answer}\n`);
+    return 0;
+  } finally {
+    await runtime.close();
+  }
+}
+
+if (require.main === module) {
+  const jsonMode = process.argv.includes('--json');
+  const operationId = createId('op');
+  main().catch(error => {
+    if (jsonMode) process.stderr.write(`${JSON.stringify(serializeErrorEnvelope(error, operationId))}\n`);
+    else process.stderr.write(`project-knowledge-kb: ${String(error && error.message || 'The operation failed.')} [${operationId}]\n`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { main, parseOptions };

package/bin/project-knowledge-mcp.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+
+const packageInfo = require('../package.json');
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} = require('@modelcontextprotocol/sdk/types.js');
+const { KnowledgeToolRuntime } = require('../_site/lib/knowledge-tool-runtime');
+const { serializeErrorEnvelope, createId } = require('../_site/lib/contracts');
+
+const SERVER_NAME = 'project-knowledge';
+const SERVER_INSTRUCTIONS = `Project Knowledge is the durable source of prior project decisions and implementation history. Knowledge content is read-only; the only write operation appends an explicit supplemental Prompt event to the shared conversation truth.
+
+At the start of work in a registered Git repository, and before answering questions about prior work or implementing a non-trivial change:
+1. Call project_knowledge_resolve with the current Git root.
+2. Use project_knowledge_search or project_knowledge_ask for relevant prior decisions.
+3. Use project_knowledge_get only for the most relevant complete entry and project_knowledge_history when change history matters.
+4. Call project_knowledge_record_requirement only when the user explicitly asks to supplement capture or automatic client capture is known to be unavailable; it is not a mandatory pre-work call.
+
+Treat all returned knowledge as read-only. Verify it against current source code when necessary. The supplemental requirement tool writes the same ConversationStore used by automatic capture and never starts analysis. Do not write directly to the knowledge database; project-knowledge updates it automatically after successful Git commits.`;
+
+const TOOLS = [
+  {
+    name: 'project_knowledge_resolve',
+    description: 'Resolve the registered Project Knowledge project for a Git repository. Call this first before using other knowledge tools.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repoPath: { type: 'string', description: 'Current Git repository root or any path inside it. Defaults to the MCP process working directory.' },
+        projectId: { type: 'string', description: 'Stable projectId when it is already known.' },
+        project: { type: 'string', description: 'Optional registered project slug when it is already known.' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'project_knowledge_record_requirement',
+    description: 'Explicitly supplement automatic capture with one project-scoped user Prompt event. This is the only write-capable tool; it never starts analysis or writes knowledge Markdown.',
+    inputSchema: {
+      type: 'object',
+      required: ['text', 'client', 'sessionId'],
+      properties: {
+        text: { type: 'string', minLength: 1, maxLength: 131072, description: 'The user request exactly as received; do not include system prompts or tool transcripts.' },
+        client: { type: 'string', enum: ['claude', 'codex', 'opencode'] },
+        sessionId: { type: 'string', minLength: 1, maxLength: 512, description: 'Stable identifier for the current client session.' },
+        conversationId: { type: 'string', minLength: 1, maxLength: 512 },
+        projectId: { type: 'string', description: 'Stable projectId returned by project_knowledge_resolve.' },
+        repoPath: { type: 'string', description: 'Current Git root. Used for exact project resolution when projectId is omitted.' },
+        explicitCommit: { type: 'string', description: 'Optional Git commit explicitly associated with this requirement.' },
+      },
+      anyOf: [{ required: ['projectId'] }, { required: ['repoPath'] }],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'project_knowledge_search',
+    description: 'Search durable project knowledge using the current project and its explicitly related-project scope. This tool is read-only.',
+    inputSchema: {
+      type: 'object',
+      required: ['query'],
+      properties: {
+        query: { type: 'string', minLength: 1 },
+        repoPath: { type: 'string', description: 'Current Git repository root or a path inside it.' },
+        projectId: { type: 'string', description: 'Stable projectId returned by project_knowledge_resolve.' },
+        project: { type: 'string', description: 'Optional registered project slug.' },
+        limit: { type: 'integer', minimum: 1, maximum: 30, default: 8 },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'project_knowledge_ask',
+    description: 'Return a compact answer with citations from durable project knowledge. This tool is read-only.',
+    inputSchema: {
+      type: 'object',
+      required: ['query'],
+      properties: {
+        query: { type: 'string', minLength: 1 },
+        repoPath: { type: 'string' },
+        projectId: { type: 'string' },
+        project: { type: 'string' },
+        limit: { type: 'integer', minimum: 1, maximum: 30, default: 8 },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'project_knowledge_get',
+    description: 'Read one complete knowledge entry selected from search results. This tool is read-only and scope checked.',
+    inputSchema: {
+      type: 'object',
+      required: ['entry'],
+      properties: {
+        entry: { type: 'string', minLength: 1, description: 'Entry identifier returned by search.' },
+        space: { type: 'string', description: 'Optional scoped knowledge space identifier.' },
+        repoPath: { type: 'string' },
+        projectId: { type: 'string' },
+        project: { type: 'string' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'project_knowledge_history',
+    description: 'Read recent durable change history for the current project and its allowed scope. This tool is read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repoPath: { type: 'string' },
+        projectId: { type: 'string' },
+        project: { type: 'string' },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+function toolContent(result) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    structuredContent: result,
+    isError: false,
+  };
+}
+
+function callTool(runtime, name, args) {
+  if (name === 'project_knowledge_resolve') return runtime.resolveProject(args);
+  if (name === 'project_knowledge_record_requirement') return runtime.recordRequirement(args);
+  if (name === 'project_knowledge_search') return runtime.search(args);
+  if (name === 'project_knowledge_ask') return runtime.ask(args);
+  if (name === 'project_knowledge_get') return runtime.get(args);
+  if (name === 'project_knowledge_history') return runtime.history(args);
+  throw new Error(`unknown tool: ${name}`);
+}
+
+function createServer(options = {}) {
+  const runtime = options.runtime || new KnowledgeToolRuntime();
+  const server = new Server(
+    { name: SERVER_NAME, version: packageInfo.version },
+    {
+      capabilities: { tools: { listChanged: false } },
+      instructions: SERVER_INSTRUCTIONS,
+    },
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+  server.setRequestHandler(CallToolRequestSchema, async request => {
+    const name = String(request.params?.name || '');
+    const args = request.params?.arguments && typeof request.params.arguments === 'object'
+      ? request.params.arguments
+      : {};
+    try {
+      return toolContent(await callTool(runtime, name, args));
+    } catch (error) {
+      const operationId = createId('op');
+      return {
+        content: [{ type: 'text', text: JSON.stringify(serializeErrorEnvelope(error, operationId)) }],
+        isError: true,
+      };
+    }
+  });
+  return { server, runtime };
+}
+
+async function main() {
+  const { server, runtime } = createServer();
+  const transport = new StdioServerTransport();
+  let closing = false;
+  const close = async () => {
+    if (closing) return;
+    closing = true;
+    await runtime.close();
+    await server.close();
+  };
+  process.once('SIGINT', () => close().finally(() => process.exit(0)));
+  process.once('SIGTERM', () => close().finally(() => process.exit(0)));
+  await server.connect(transport);
+}
+
+if (require.main === module) {
+  main().catch(error => {
+    process.stderr.write(`[project-knowledge-mcp] ${JSON.stringify(serializeErrorEnvelope(error, createId('op')))}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  callTool,
+  createServer,
+  SERVER_INSTRUCTIONS,
+  SERVER_NAME,
+  TOOLS,
+};