codebase_about

Instructions

Implementation Reference

• src/index.ts:460-467 (registration)

  Tool 'codebase_about' is registered via server.tool() with description and delegates to handleManageTool('codebase_about', args).

  server.tool(
    "codebase_about",
    "Display information about SocratiCode — what it is, its tools and how to use it. Use this to get a quick overview of the MCP tools and their purpose.",
    {},
    async (args) => ({
      content: [{ type: "text", text: await handleManageTool("codebase_about", args) }],
    }),
  );

• src/tools/manage-tools.ts:197-247 (handler)

  Handler case for 'codebase_about' in handleManageTool(). Returns a multi-line informational string about SocratiCode, including infrastructure status and quick reference of all tools.

  case "codebase_about": {
    const infraStatus = await getInfraStatusSummary();
    return [
      "SocratiCode — Codebase intelligence MCP server",
      "Hybrid semantic + keyword search, dependency graphs, context artifacts.",
      "",
      ...infraStatus,
      "",
      "━━━ Quick Reference ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
      "",
      "Indexing:",
      "  codebase_index        — Index a project (background). Poll with codebase_status.",
      "  codebase_update       — Incremental re-index (changed files only).",
      "  codebase_stop         — Gracefully stop in-progress indexing.",
      "  codebase_remove       — Delete a project's index.",
      "  codebase_watch        — Start/stop/status of live file watcher.",
      "",
      "Search:",
      "  codebase_search       — Hybrid semantic + BM25 search. Use after indexing.",
      "  codebase_status       — Check index status, progress, watcher state.",
      "",
      "Dependency Graph:",
      "  codebase_graph_build  — Build AST-based dependency graph (background).",
      "  codebase_graph_query  — Imports & dependents for a file.",
      "  codebase_graph_stats  — Graph stats: files, edges, most connected, orphans.",
      "  codebase_graph_circular — Find circular dependencies.",
      "  codebase_graph_visualize — Mermaid diagram (default) or interactive HTML explorer (mode=\"interactive\"), colour-coded by language.",
      "  codebase_graph_status — Poll graph build progress.",
      "  codebase_graph_remove — Delete a project's graph.",
      "",
      "Context Artifacts:",
      "  codebase_context        — List artifacts (.socraticodecontextartifacts.json).",
      "  codebase_context_search — Search schemas, API specs, configs, docs.",
      "  codebase_context_index  — Re-index artifacts (usually automatic).",
      "  codebase_context_remove — Delete indexed artifacts.",
      "",
      "Management:",
      "  codebase_health       — Check Docker, Qdrant, embeddings status.",
      "  codebase_list_projects — List all indexed projects.",
      "",
      "━━━ Typical Workflow ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
      "",
      "1. codebase_index → poll codebase_status until complete.",
      "2. codebase_search to find code. Search before reading files.",
      "3. codebase_graph_query to explore dependencies.",
      "4. codebase_context_search for schemas, API specs, configs.",
      "",
      `v${SOCRATICODE_VERSION} · © 2026 Giancarlo Erra — Altaire Limited · AGPL-3.0`,
      "https://github.com/giancarloerra/socraticode",
    ].join("\n");
  }

• src/tools/manage-tools.ts:12-56 (helper)

  Helper function getInfraStatusSummary() used by the codebase_about handler to embed infrastructure status (Docker, Qdrant, embeddings) into the output.

  /** Quick infrastructure check for embedding in codebase_about */
  async function getInfraStatusSummary(): Promise<string[]> {
    const lines: string[] = [];
    const config = getEmbeddingConfig();
    try {
      if (QDRANT_MODE === "external") {
        const endpoint = QDRANT_URL ?? `http://${QDRANT_HOST}:${QDRANT_PORT}`;
        try {
          await listCodebaseCollections(); // throws if unreachable
          const provider = await getEmbeddingProvider();
          const health = await provider.healthCheck();
          if (health.available) {
            lines.push(`Infrastructure: ✅ External Qdrant reachable (${endpoint}), ${config.embeddingProvider} embeddings ready`);
          } else {
            lines.push(`Infrastructure: ⚠️ External Qdrant reachable (${endpoint}), but ${config.embeddingProvider} embeddings not ready`);
          }
        } catch {
          lines.push(`Infrastructure: ❌ Cannot reach external Qdrant at ${endpoint}`);
          lines.push("  Check QDRANT_URL / QDRANT_HOST and make sure the server is running.");
        }
      } else {
        const docker = await isDockerAvailable();
        if (!docker) {
          lines.push("Infrastructure: ❌ Docker not available");
          lines.push("  Install from https://docker.com and start Docker Desktop.");
          return lines;
        }
        const qdrant = await isQdrantRunning();
        const provider = await getEmbeddingProvider();
        const health = await provider.healthCheck();
        if (qdrant && health.available) {
          lines.push(`Infrastructure: ✅ All services running (Docker, Qdrant, ${config.embeddingProvider} embeddings)`);
        } else {
          const missing: string[] = [];
          if (!qdrant) missing.push("Qdrant");
          if (!health.available) missing.push(`${config.embeddingProvider} embeddings`);
          lines.push(`Infrastructure: ⚠️ Docker OK, but ${missing.join(" and ")} not running`);
          lines.push("  Run codebase_index or codebase_health to auto-start services.");
        }
      }
    } catch {
      lines.push("Infrastructure: ❓ Could not check status");
    }
    return lines;
  }