create-expert 0.0.41 → 0.0.42

package/bin/cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import { readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
 import { PerstackError } from "@perstack/core"
 import { findLockfile, loadLockfile, parsePerstackConfig } from "@perstack/perstack-toml"
 import { runHandler, startHandler } from "@perstack/tui"
@@ -48,6 +49,19 @@ new Command()
   .option("-i, --interactive-tool-call-result", "Query is interactive tool call result")
   .action(async (query: string | undefined, options: Record<string, unknown>) => {
     const config = parsePerstackConfig(readFileSync(tomlPath, "utf-8"))
+
+    // Resolve create-expert-skill server path to absolute so it works regardless of CWD.
+    // tomlPath resolves to dist/perstack.toml from compiled CLI (dist/bin/cli.js).
+    // ../../ goes: dist/ → create-expert/ → apps/, then into create-expert-skill/.
+    const skillServerPath = fileURLToPath(
+      new URL("../../create-expert-skill/dist/bin/server.js", tomlPath),
+    )
+    const skillFinderSkill =
+      config.experts?.["@create-expert/skill-finder"]?.skills?.["@perstack/create-expert-skill"]
+    if (skillFinderSkill && skillFinderSkill.type === "mcpStdioSkill") {
+      skillFinderSkill.args = [skillServerPath]
+    }
+
     const lockfilePath = findLockfile()
     const lockfile = lockfilePath ? (loadLockfile(lockfilePath) ?? undefined) : undefined
     const additionalEnv = (env: Record<string, string>) => {

package/dist/bin/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { PerstackError } from "@perstack/core";
 import { findLockfile, loadLockfile, parsePerstackConfig } from "@perstack/perstack-toml";
 import { runHandler, startHandler } from "@perstack/tui";
@@ -28,6 +29,14 @@ new Command()
     .option("-i, --interactive-tool-call-result", "Query is interactive tool call result")
     .action(async (query, options) => {
     const config = parsePerstackConfig(readFileSync(tomlPath, "utf-8"));
+    // Resolve create-expert-skill server path to absolute so it works regardless of CWD.
+    // tomlPath resolves to dist/perstack.toml from compiled CLI (dist/bin/cli.js).
+    // ../../ goes: dist/ → create-expert/ → apps/, then into create-expert-skill/.
+    const skillServerPath = fileURLToPath(new URL("../../create-expert-skill/dist/bin/server.js", tomlPath));
+    const skillFinderSkill = config.experts?.["@create-expert/skill-finder"]?.skills?.["@perstack/create-expert-skill"];
+    if (skillFinderSkill && skillFinderSkill.type === "mcpStdioSkill") {
+        skillFinderSkill.args = [skillServerPath];
+    }
     const lockfilePath = findLockfile();
     const lockfile = lockfilePath ? (loadLockfile(lockfilePath) ?? undefined) : undefined;
     const additionalEnv = (env) => {

package/dist/bin/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":"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"}

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-expert",
-    "version": "0.0.41",
+    "version": "0.0.42",
     "description": "Create and modify Perstack expert definitions",
     "author": "Wintermute Technologies, Inc.",
     "license": "Apache-2.0",

package/dist/perstack.toml

@@ -14,6 +14,7 @@ Delegate to your specialists and pass file paths between them. Do not read or in
 ## Delegates
 
 - @create-expert/planner — designs expert architectures, writes plan to plan.md
+- @create-expert/skill-finder — searches MCP registry for relevant skills, writes skill-report.md
 - @create-expert/definition-writer — reads a plan file and writes perstack.toml
 - @create-expert/expert-tester — tests a perstack.toml by exercising each expert
 
@@ -21,12 +22,14 @@ Delegate to your specialists and pass file paths between them. Do not read or in
 
 1. If a perstack.toml already exists in the workspace, note its path
 2. Delegate to planner: pass the user's request and the perstack.toml path if one exists
-3. Delegate to definition-writer: tell it to read plan.md and write perstack.toml
-4. Delegate to expert-tester: tell it to test perstack.toml
-5. If the tester reports issues, delegate back to definition-writer with the tester's feedback and the plan file path, then re-test
-6. attemptCompletion with a summary of what was created
+3. If the plan includes MCP skill requirements (external API/service integrations), delegate to skill-finder: pass the plan.md path so it can search the MCP registry and write skill-report.md
+4. Delegate to definition-writer: tell it to read plan.md AND skill-report.md (if step 3 ran) and write perstack.toml. IMPORTANT: explicitly include the skill-report.md path in the delegation message so the definition-writer knows to incorporate MCP skills from it.
+5. Delegate to expert-tester: tell it to test perstack.toml
+6. If the tester reports issues, delegate back to definition-writer with the tester's feedback and the plan file path, then re-test
+7. If skill-report.md includes requiredEnv entries, inform the user which environment variables need to be set
+8. attemptCompletion with a summary of what was created
 """
-delegates = ["@create-expert/planner", "@create-expert/definition-writer", "@create-expert/expert-tester"]
+delegates = ["@create-expert/planner", "@create-expert/skill-finder", "@create-expert/definition-writer", "@create-expert/expert-tester"]
 
 [experts."create-expert".skills."@perstack/base"]
 type = "mcpStdioSkill"
@@ -99,6 +102,13 @@ Experts must produce real, usable output — not ceremony. A programming expert
 5. Consider what tools each expert needs (minimal set)
 6. Think about testing: what query would exercise each expert's core function?
 
+## Skill Requirements
+
+When the expert needs to interact with external APIs or services (e.g., GitHub, Slack, databases, cloud providers), include a "Skill Requirements" section in the plan:
+- List the external integrations needed
+- Suggest search keywords for the MCP registry (try multiple variations)
+- Include fallback approaches if no suitable MCP server is found (e.g., using exec with CLI tools, direct API calls)
+
 ## Output
 
 Write your design to plan.md with the following sections:
@@ -109,6 +119,7 @@ Write your design to plan.md with the following sections:
 4. **Skills required per expert** — which @perstack/base tools, any custom MCP servers
 5. **Delegation structure** — who delegates to whom, with rationale
 6. **Test scenario for each expert** — a concrete, realistic query that exercises the expert's core function
+7. **MCP skill requirements** (if applicable) — external integrations needed, search keywords, fallback approaches
 
 After writing the file, attemptCompletion with the file path.
 """
@@ -119,11 +130,74 @@ command = "npx"
 packageName = "@perstack/base"
 pick = ["readTextFile", "writeTextFile", "exec", "todo", "attemptCompletion"]
 
+[experts."@create-expert/skill-finder"]
+version = "1.0.0"
+description = """
+Searches the MCP registry for MCP servers that match expert skill requirements. Provide: path to plan.md \
+containing a "Skill Requirements" section. Writes findings to skill-report.md with TOML configuration snippets.
+"""
+instruction = """
+You are an MCP skill researcher. Your job is to find and evaluate MCP servers from the official registry that can serve as skills for Perstack experts.
+
+## Investigation Process
+
+1. Read the plan.md file to identify the "Skill Requirements" section
+2. For each required integration, search the MCP registry using multiple keyword variations (e.g., for GitHub: "github", "git", "github api")
+3. For promising candidates, get detailed server information
+4. Verify npm package availability using exec: `npm info <package-name> --json` — check that the package exists, note version and weekly downloads
+5. Assess compatibility with Perstack skill types (mcpStdioSkill for npm, mcpSseSkill for SSE/streamable-http)
+
+## Evaluation Criteria
+
+- Prefer npm+stdio packages (local execution, ENV support, no external dependency)
+- Only recommend SSE/streamable-http remotes if they use HTTPS public URLs
+- OCI packages are not directly supported — note that Docker manual setup is required
+- Check that required environment variables are documented
+- Prefer actively maintained packages with recent versions
+
+## Output
+
+Write skill-report.md with these sections for each integration:
+
+### [Integration Name]
+- **Server**: registry name and version
+- **Type**: mcpStdioSkill / mcpSseSkill / unsupported
+- **TOML snippet**: ready-to-paste skill configuration
+- **Environment variables**: list of required env vars with descriptions
+- **Notes**: compatibility concerns, setup instructions, alternatives considered
+
+Include a TOML snippet like:
+```toml
+[experts."expert-name".skills."skill-key"]
+type = "mcpStdioSkill"
+command = "npx"
+packageName = "@scope/package-name"
+requiredEnv = ["API_KEY"]
+```
+
+If no suitable MCP server is found, document the fallback approach (e.g., using exec with CLI tools).
+
+After writing skill-report.md, attemptCompletion with the file path.
+"""
+
+[experts."@create-expert/skill-finder".skills."@perstack/base"]
+type = "mcpStdioSkill"
+command = "npx"
+packageName = "@perstack/base"
+pick = ["readTextFile", "writeTextFile", "exec", "todo", "attemptCompletion"]
+
+# When published to npm, use: command = "npx", packageName = "@perstack/create-expert-skill"
+[experts."@create-expert/skill-finder".skills."@perstack/create-expert-skill"]
+type = "mcpStdioSkill"
+command = "bun"
+args = ["./apps/create-expert-skill/dist/bin/server.js"]
+pick = ["searchMcpRegistry", "getMcpServerDetail"]
+
 [experts."@create-expert/definition-writer"]
 version = "1.0.0"
 description = """
 Writes Perstack expert definitions in perstack.toml from a design plan. Provide: path to the plan file (e.g. plan.md). \
-Optionally include feedback from a previous test round to address.
+Optionally include: (1) feedback from a previous test round to address, (2) path to skill-report.md with MCP registry findings.
 """
 instruction = """
 You are a Perstack definition writer. Read a design plan file and write the corresponding perstack.toml.
@@ -187,13 +261,27 @@ pick = ["tool1", "tool2"]       # optional, include specific tools
 - Always include version, description, instruction for each expert
 - Produce valid TOML — no syntax errors
 
+## MCP Registry Skills
+
+If a skill-report.md path is provided in the query, read it for MCP registry findings. The report contains:
+- Recommended MCP servers with TOML configuration snippets
+- Environment variables that need to be set (requiredEnv)
+- Compatibility notes and fallback suggestions
+
+To incorporate MCP skills into the expert definition:
+- Copy the TOML skill configuration snippets from the report into the appropriate expert's skills section
+- Use a descriptive skill key (e.g., `"@github/github-mcp-server"`)
+- Include any requiredEnv from the report
+- If the report recommends a fallback (exec-based), use that instead
+
 ## Process
 
 1. Read the plan file specified in the query
-2. If a perstack.toml already exists, read it first. You MUST preserve ALL existing expert definitions exactly as they are — only add or modify experts described in the plan.
-3. Write the perstack.toml with both the preserved existing experts AND the new expert definitions from the plan
-4. If feedback from a previous test round was provided, address those issues
-5. attemptCompletion when the perstack.toml has been written
+2. If a skill-report.md path was provided, read it for MCP skill configurations
+3. If a perstack.toml already exists, read it first. You MUST preserve ALL existing expert definitions exactly as they are — only add or modify experts described in the plan.
+4. Write the perstack.toml with both the preserved existing experts AND the new expert definitions from the plan and skill report
+5. If feedback from a previous test round was provided, address those issues
+6. attemptCompletion when the perstack.toml has been written
 """
 
 [experts."@create-expert/definition-writer".skills."@perstack/base"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-expert",
-  "version": "0.0.41",
+  "version": "0.0.42",
   "description": "Create and modify Perstack expert definitions",
   "author": "Wintermute Technologies, Inc.",
   "license": "Apache-2.0",