list_concepts

Instructions

Implementation Reference

• pi/extensions/index.ts:208-221 (schema)

  Schema/definition for the list_concepts tool including description and optional top_k parameter

  {
    mcpName: "list_concepts",
    label: "List Concepts",
    description:
      "List the project's domain vocabulary ranked by importance. " +
      "A semantic overview of what this codebase is about.",
    promptSnippet:
      "ontomics_list_concepts: ranked domain vocabulary overview",
    parameters: Type.Object({
      top_k: Type.Optional(
        Type.Integer({ description: "Max concepts to return" }),
      ),
    }),
  },

• pi/extensions/index.ts:362-387 (registration)

  Registration of list_concepts (and all other tools) via pi.registerTool. The actual handler logic delegates to an external ontomics binary via McpClient.callTool.

  for (const def of toolDefs()) {
    pi.registerTool({
      name: `ontomics_${def.mcpName}`,
      label: def.label,
      description: def.description,
      promptSnippet: def.promptSnippet,
      promptGuidelines: [
        "Use ontomics tools BEFORE grep/glob for semantic codebase questions.",
      ],
      parameters: def.parameters,
      async execute(_toolCallId, params, _signal, onUpdate, _ctx) {
        onUpdate?.({
          content: [{ type: "text", text: `Querying ontomics: ${def.mcpName}...` }],
        });
        try {
          const mcp = await getClient();
          const text = await mcp.callTool(def.mcpName, cleanArgs(params));
          return { content: [{ type: "text", text }] };
        } catch (err) {
          throw new Error(
            `ontomics ${def.mcpName} failed: ${err instanceof Error ? err.message : String(err)}`,
          );
        }
      },
    });
  }

• pi/extensions/index.ts:372-387 (handler)

  Handler/execute function for list_concepts — sends a JSON-RPC call named 'list_concepts' to the ontomics binary via stdio and returns the text response

      async execute(_toolCallId, params, _signal, onUpdate, _ctx) {
        onUpdate?.({
          content: [{ type: "text", text: `Querying ontomics: ${def.mcpName}...` }],
        });
        try {
          const mcp = await getClient();
          const text = await mcp.callTool(def.mcpName, cleanArgs(params));
          return { content: [{ type: "text", text }] };
        } catch (err) {
          throw new Error(
            `ontomics ${def.mcpName} failed: ${err instanceof Error ? err.message : String(err)}`,
          );
        }
      },
    });
  }

• pi/extensions/index.ts:44-54 (helper)

  McpClient.callTool helper that dispatches the tool call via JSON-RPC to the ontomics server process

  async callTool(
    name: string,
    args: Record<string, unknown>,
  ): Promise<string> {
    const result = (await this.request("tools/call", {
      name,
      arguments: args,
    })) as { content?: Array<{ text?: string }> };
    const text = result.content?.[0]?.text ?? JSON.stringify(result);
    return text;
  }

• pi/extensions/index.ts:352-360 (helper)

  Helper to strip undefined keys before passing parameters (including top_k for list_concepts) to the MCP server

  function cleanArgs(
    params: Record<string, unknown>,
  ): Record<string, unknown> {
    const out: Record<string, unknown> = {};
    for (const [k, v] of Object.entries(params)) {
      if (v !== undefined) out[k] = v;
    }
    return out;
  }