@thierrynakoa/fire-flow 12.2.2 → 13.0.1

package/skills-library/_general/growth-marketing/oss-daily-growth-intelligence.md

@@ -0,0 +1,224 @@
+---
+name: oss-daily-growth-intelligence
+category: growth-marketing
+version: 1.0.0
+contributed: 2026-03-10
+contributor: fire-flow
+last_updated: 2026-03-10
+tags: [github, npm, analytics, marketing, growth, open-source, social-media, psyops]
+difficulty: medium
+scope: general
+---
+
+# OSS Daily Growth Intelligence
+
+## Problem
+
+After launching an open-source project you need to:
+1. Track daily traction without manually hitting GitHub/npm every morning
+2. Maintain a visual report that you can screenshot and share
+3. Systematically boost exposure beyond the initial launch spike
+
+Manual checking is inconsistent. Post-launch traffic decays fast. Most OSS projects die after the first viral day because the author stops pushing. This skill captures the full daily intelligence + marketing loop.
+
+## Solution Pattern
+
+### Part 1 — Daily Metrics Pull (7AM loop)
+
+Run every morning at 7AM via `/loop 24h`:
+
+```bash
+# GitHub traffic (views + clones)
+gh api repos/{OWNER}/{REPO}/traffic/views
+gh api repos/{OWNER}/{REPO}/traffic/clones
+gh api repos/{OWNER}/{REPO}/traffic/popular/referrers
+gh api repos/{OWNER}/{REPO}/traffic/popular/paths
+
+# Repo stats
+gh api repos/{OWNER}/{REPO} --jq '{stars:.stargazers_count,forks:.forks_count}'
+
+# npm daily downloads
+curl -s "https://api.npmjs.org/downloads/range/{DATE_RANGE}/{PACKAGE}"
+```
+
+Update `~/.claude/mission-control/fire-flow-traffic.json` with new data.
+Update `Documents/Claude Reports/fire-flow-traffic-report.html` (full dashboard).
+Update `Documents/Claude Reports/fire-flow-launch-card.html` (Facebook post card).
+
+Summarize changes vs yesterday:
+- Stars delta, forks delta
+- Views delta, new top referrers
+- npm installs delta
+- Flag any anomalies (traffic spike = someone shared it)
+
+### Part 2 — Insight Output
+
+Each morning's loop should produce:
+
+```
+fire-flow Daily Pulse — {DATE}
+────────────────────────────
+Stars:    {N} (+{delta})
+Forks:    {N} (+{delta})
+Views:    {N} (+{delta})  ← {top referrer today}
+npm:      {N} (+{delta})
+────────────────────────────
+Alert: {any spike or trend note}
+Marketing suggestion: {one action from the radical tactics list}
+```
+
+## Loop Setup Command
+
+Start at 7AM daily (run this command AT 7AM so the 24h cycle aligns):
+
+```
+/loop 24h Pull GitHub and npm traffic for ThierryN/fire-flow using gh CLI and npm registry API. Update C:\Users\Thierry\Documents\Claude Reports\fire-flow-traffic.json with new daily data. Compare to previous day. Update both HTML report files. Output the daily pulse summary with marketing suggestion.
+```
+
+## C3 Integration
+
+Add to `~/.claude/mission-control/reminders.json`:
+- Daily 7AM reminder to start the loop if not already running
+- Weekly Sunday reminder to post the traffic card on Facebook
+
+---
+
+## Part 3 — Radical Marketing Tactics (OSS Psyops)
+
+These are proven psychological triggers for OSS growth. Apply one per day.
+
+---
+
+### Tier 1: High-Leverage Posts (do first)
+
+**1. Transparent Metrics Post**
+Post the fire-flow-launch-card.html screenshot directly to every AI/Claude Facebook group.
+Caption: "Day {N}: fire-flow — {stars} stars, {downloads} downloads, {views} GitHub views in {N} days. Free plugin for Claude Code."
+Why it works: Real numbers trigger FOMO and credibility simultaneously. Most devs never share metrics. The transparency is disarming.
+
+**2. The Before/After Story**
+"I vibe-coded a 60,000 line app over 6 months. fire-flow helped me rebuild it clean — 19,986 lines, full TypeScript, 137 tests — in one autonomous session."
+Why it works: Specific numbers + personal story = highest-engagement post format. This is the Scribal Priest rebuild story. USE IT.
+
+**3. The Live Challenge**
+"Drop your hardest build task below. I'll run fire-flow on it and post the result."
+Why it works: Engagement bait + live demo + social proof. Every comment = algorithm fuel.
+
+**4. The Contrast Hook**
+"Everyone is using Claude Code. Almost nobody knows there's a free planning + execution layer that eliminates token waste and random hallucinations."
+Why it works: In-group identity + exclusivity + implies the reader is about to get an unfair advantage.
+
+---
+
+### Tier 2: Discovery Channels (sustained traffic)
+
+**5. Product Hunt Launch**
+- Schedule for Tuesday or Wednesday at 00:01 PT
+- Pre-build hunter list (DM 20 people who upvote AI tools)
+- Tagline: "The missing planning layer for Claude Code — 511+ battle-tested skills"
+- First comment: the before/after story
+
+**6. Show HN (Hacker News)**
+Title: "Show HN: fire-flow – orchestration system for Claude Code (66% codebase reduction)"
+Body: Lead with the Scribal Priest rebuild numbers. Link to GitHub.
+Best time: Monday/Tuesday 9AM ET
+
+**7. Reddit Posts**
+- r/ClaudeAI — "I built a planning/execution plugin for Claude Code. 36 stars in 8 days."
+- r/LocalLLaMA — Focus on token efficiency angle
+- r/programming — Focus on the autonomous rebuild story
+- r/SideProject — "Built this for myself, 925 people downloaded it in 8 days"
+
+**8. Awesome Lists Submission**
+Submit to:
+- awesome-claude-code (GitHub)
+- awesome-ai-agents
+- awesome-llm-tools
+- awesome-chatgpt-prompts (stretch)
+These drive sustained long-tail organic installs for months.
+
+---
+
+### Tier 3: Parasitic Growth (amplify existing audiences)
+
+**9. Reply Seeding**
+Find viral posts about Claude Code from @swyx, @karpathy, Claude official (@AnthropicAI), and any AI tool posts with 100+ likes. Reply with:
+"This is where fire-flow helps — [specific relevant use case]. Free plugin: github.com/ThierryN/fire-flow"
+Why it works: You get the eyeballs of an already-engaged audience with zero spend.
+
+**10. Micro-Influencer DMs (10 people)**
+Find developers with 5k–50k followers who post about AI coding tools.
+Message: "Hey {name}, I built a free orchestration plugin for Claude Code. {specific reason it's relevant to their content}. Want me to send you a private demo?"
+10 DMs → 2-3 responses → 1-2 posts = 500+ new installs.
+
+**11. YouTube Short (60 seconds)**
+Screen record: Open terminal → `npx @thierrynakoa/fire-flow` → pick a project → watch fire-flow plan and execute a feature autonomously.
+No voiceover needed. Add captions. Post to YouTube Shorts, TikTok, Instagram Reels.
+Why it works: Video of code running autonomously is hypnotic. Gets shared without prompting.
+
+---
+
+### Tier 4: Content Momentum (algorithm food)
+
+**12. The Build Diary (daily serial)**
+Post every day: "Day {N} of fire-flow:"
+Keep it to 2–3 lines + one screenshot.
+Day 8: 36 stars. Day 9: 38 stars. Small wins compound.
+Serial content trains the algorithm to push your account.
+
+**13. Dev.to / Hashnode / Medium Article**
+Title: "How fire-flow cut my Claude Code sessions from 3 hours to 45 minutes"
+This ranks on Google for "Claude Code plugin", "Claude Code orchestration" etc.
+One article = 6 months of passive discovery traffic.
+
+**14. Controversial Take (engagement bait)**
+"Hot take: Using Claude Code without a planning layer is like deploying to prod without tests. You'll get there, but not the way you wanted."
+Replies = reach. Even disagreement = algorithm boost.
+
+**15. The "0 to 925" Story**
+"8 days ago I pushed a GitHub repo. Here's exactly what happened:"
+Then tell the story: no marketing budget, just sharing in Facebook groups, 65% of traffic from FB, 373 npm installs, viral day = 558 views.
+Meta-content about building in public performs extremely well.
+
+---
+
+## When to Use Each Tactic
+
+| Tactic | When | Expected Result |
+|--------|------|----------------|
+| Transparent Metrics Post | Daily (morning) | 50–200 views/post |
+| Before/After Story | Once now, repurpose | Highest engagement, shareable |
+| Live Challenge | When engagement slows | 20–50 comments |
+| Product Hunt | Week 2–3 | 100–500 new stars/installs |
+| Show HN | Any weekday morning | 200–2000 views if it hits front page |
+| Reddit posts | 1 per community | 50–500 visits per post |
+| Awesome Lists | One-time, this week | Steady 10–30 installs/week long-term |
+| Reply Seeding | Daily (5 min) | Compound visibility over weeks |
+| Micro-influencer DMs | 10 this week | 1–3 posts from real users |
+| YouTube Short | ASAP | 500–5000 views within 2 weeks |
+| Build Diary | Daily | Algorithm momentum |
+
+---
+
+## Anti-Patterns (What NOT to Do)
+
+- **Do NOT spam** the same post in 10 groups at the same time. Stagger by 2–3 days.
+- **Do NOT lead with features** — lead with outcomes and stories. Nobody shares "I added X feature."
+- **Do NOT ignore replies** — respond to every comment in the first hour. Algorithm gold.
+- **Do NOT post only when you have something new** — consistency > novelty for discovery.
+- **Do NOT skip the daily metrics pull** — you can't market intelligently without knowing what's moving.
+
+---
+
+## Related Skills
+
+- `fire-flow-traffic-report` — HTML dashboard template
+- `github-api-patterns` — gh CLI reference
+- `social-media-post-card` — Facebook post image generation
+
+## References
+
+- GitHub Traffic API: https://docs.github.com/en/rest/metrics/traffic
+- npm Downloads API: https://api.npmjs.org/downloads/range/{period}/{package}
+- fire-flow repo: github.com/ThierryN/fire-flow
+- Reports: `C:\Users\Thierry\Documents\Claude Reports\`

package/skills-library/_general/integrations/claude-code-local-mcp-integration.md

@@ -0,0 +1,250 @@
+---
+name: claude-code-local-mcp-integration
+category: integrations
+version: 1.0.0
+contributed: 2026-03-01
+contributor: your-memory-repo
+last_updated: 2026-03-01
+contributors:
+  - your-memory-repo
+tags: [mcp, claude-code, stdio, local-server, debugging, configuration]
+difficulty: easy
+usage_count: 0
+success_rate: 100
+---
+
+# Claude Code Local MCP Server Integration
+
+## Problem
+
+Building an MCP server is well-documented, but registering it with Claude Code, configuring environment variables, debugging startup failures, and testing locally are NOT. Common issues:
+
+- Server configured in `mcp.json` but tools don't appear after restart
+- Server works standalone but fails when Claude Code spawns it
+- Environment variables not passed through correctly
+- No visibility into why a server failed to connect
+- Server name shows "not found" in `/mcp` dialog
+
+## Solution Pattern
+
+Follow this integration checklist to reliably register, test, and debug local stdio MCP servers with Claude Code.
+
+## Registration — mcp.json
+
+All MCP servers for Claude Code are registered in `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["tsx", "C:/path/to/my-server.ts"],
+      "env": {
+        "QDRANT_URL": "http://localhost:6335",
+        "API_KEY": "${MCP_MY_SERVER_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+**Key rules:**
+- **Server name** (`my-server`): kebab-case, used in `/mcp` dialog and tool prefixes
+- **command**: The executable (`npx`, `node`, `python`, etc.)
+- **args**: Arguments passed to the command (for TypeScript, use `["tsx", "/absolute/path.ts"]`)
+- **env**: Environment variables passed to the server process
+- **`${VAR_NAME}` syntax**: References variables from `~/.claude/.env` — use for secrets
+- **Absolute paths**: Always use absolute paths in args; relative paths resolve from Claude Code's CWD, not the server's location
+
+### HTTP Transport Alternative
+
+For remote or shared servers:
+
+```json
+{
+  "mcpServers": {
+    "my-remote-server": {
+      "type": "http",
+      "url": "https://my-server.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${MCP_MY_SERVER_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Server Lifecycle
+
+1. **Session start**: Claude Code reads `mcp.json` and spawns all configured servers
+2. **Connection**: Each server's stdio transport is connected; tools are discovered
+3. **Mid-session**: `/mcp` dialog shows status and allows restart
+4. **Session end**: All server processes are terminated
+
+**Critical timing**: If a server fails during step 1-2, it will NOT appear in the session. Claude Code does not retry failed servers automatically.
+
+## Testing Before Registration
+
+**Always test the server standalone before registering with Claude Code:**
+
+```bash
+# Test 1: Does the server start without errors?
+cd /path/to/project
+npx tsx src/mcp-server.ts
+# Should see startup message on stderr (stdout is reserved for JSON-RPC)
+
+# Test 2: Does it respond to MCP protocol?
+# Send a JSON-RPC initialize request on stdin:
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-01-01","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | npx tsx src/mcp-server.ts
+
+# Test 3: Are dependencies running?
+curl -s http://localhost:6335/collections  # Qdrant
+curl -s http://localhost:11434/api/version  # Ollama
+```
+
+## Debugging Startup Failures
+
+When tools don't appear after Claude Code restart:
+
+### Step 1: Check `/mcp` Dialog
+Run `/mcp` in Claude Code. Look for:
+- Server listed but status "error" → server crashed during startup
+- Server not listed at all → invalid mcp.json syntax or server name mismatch
+
+### Step 2: Test Standalone
+```bash
+# Run with the EXACT same env vars Claude Code would pass
+QDRANT_URL=http://localhost:6335 OLLAMA_URL=http://localhost:11434 npx tsx src/mcp-server.ts
+```
+
+### Step 3: Check Dependencies
+The most common failure: the server starts but crashes connecting to a dependency (Qdrant, Ollama, database) that isn't running.
+
+```bash
+# Check Qdrant
+curl -s http://localhost:6335/collections && echo "OK" || echo "QDRANT DOWN"
+
+# Check Ollama
+curl -s http://localhost:11434/api/version && echo "OK" || echo "OLLAMA DOWN"
+```
+
+### Step 4: Check `npx` Resolution
+`npx tsx` needs to resolve `tsx` from the project's `node_modules` or globally. If the server is outside a Node project:
+
+```bash
+# Install tsx globally as fallback
+npm install -g tsx
+```
+
+### Step 5: Validate mcp.json Syntax
+```bash
+# Parse check
+node -e "JSON.parse(require('fs').readFileSync(process.env.HOME+'/.claude/mcp.json','utf-8'))" && echo "VALID" || echo "INVALID JSON"
+```
+
+## Common Failure Modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Server "not found" in `/mcp` | Invalid JSON in mcp.json | Fix syntax, restart session |
+| Server listed but no tools | Server crashed after registering | Check stderr logs, test standalone |
+| Tools appear but return errors | Dependencies not running | Start Qdrant/Ollama/DB before session |
+| `${VAR}` not resolved | Missing from `~/.claude/.env` | Add variable to .env file |
+| Works in bash, fails in Claude Code | Different working directory | Use absolute paths everywhere |
+| Intermittent failures | Server startup race condition | Add connection retry logic in server |
+
+## Server Code Best Practices
+
+```typescript
+// 1. Log to STDERR only (stdout is JSON-RPC transport)
+console.error('Server starting...');  // OK
+console.log('Debug info');            // BREAKS the protocol
+
+// 2. Graceful dependency checks
+async function main() {
+  try {
+    await checkQdrantConnection();
+    await checkOllamaConnection();
+  } catch (err) {
+    console.error('Dependency check failed:', err.message);
+    console.error('Server will start but some tools may fail.');
+    // DON'T exit — let the server start so Claude Code can see it
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('MCP server running (stdio)');
+}
+
+// 3. Tool-level error handling (never crash the server)
+server.tool('my_tool', 'Description', schema, async (params) => {
+  try {
+    const result = await doWork(params);
+    return { content: [{ type: 'text', text: formatResult(result) }] };
+  } catch (error) {
+    return {
+      content: [{ type: 'text', text: `Error: ${error.message}` }],
+      isError: true,  // Tells Claude this is an error, not a result
+    };
+  }
+});
+```
+
+## Environment Variable Pattern
+
+```
+# ~/.claude/.env
+MCP_QDRANT_URL=http://localhost:6335
+MCP_OLLAMA_URL=http://localhost:11434
+MCP_MY_SECRET_KEY=sk-abc123
+```
+
+```json
+// ~/.claude/mcp.json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["tsx", "C:/path/to/server.ts"],
+      "env": {
+        "QDRANT_URL": "${MCP_QDRANT_URL}",
+        "OLLAMA_URL": "${MCP_OLLAMA_URL}",
+        "SECRET_KEY": "${MCP_MY_SECRET_KEY}"
+      }
+    }
+  }
+}
+```
+
+## When to Use
+
+- Registering any locally-built MCP server with Claude Code
+- Debugging why MCP tools don't appear after session restart
+- Setting up environment variables for local services (Qdrant, Ollama, databases)
+- Troubleshooting server startup failures
+
+## When NOT to Use
+
+- Building the MCP server itself (use the mcp-builder skill instead)
+- Deploying remote MCP servers (use Cloudflare Workers MCP skill)
+- Using existing marketplace MCP servers (they handle their own registration)
+
+## Common Mistakes
+
+- **Logging to stdout** — breaks JSON-RPC protocol; always use `console.error()`
+- **Relative paths in mcp.json** — resolve from Claude Code's CWD, not server location; use absolute paths
+- **Crashing on missing dependencies** — let the server start so Claude Code registers it; fail gracefully at the tool level
+- **Not testing standalone first** — always verify the server works in isolation before registering
+- **Forgetting to restart Claude Code** — MCP servers are discovered at session start; mid-session changes to mcp.json require `/mcp` restart or new session
+
+## Related Skills
+
+- [mcp-composite-tool-orchestration](./mcp-composite-tool-orchestration.md) - Building composite multi-step MCP tools
+- [node_mcp_server](../../marketplaces/anthropic-agent-skills/skills/mcp-builder/reference/node_mcp_server.md) - Base MCP server architecture
+- [mcp_best_practices](../../marketplaces/anthropic-agent-skills/skills/mcp-builder/reference/mcp_best_practices.md) - Naming, security, transport selection
+
+## References
+
+- Proven on: your-memory-repo codebase-context MCP server (Feb 2026)
+- Common failures documented from 3 sessions of MCP debugging
+- Claude Code MCP architecture: stdio transport, mcp.json configuration

package/skills-library/_general/integrations/mcp-composite-tool-orchestration.md

@@ -0,0 +1,200 @@
+---
+name: mcp-composite-tool-orchestration
+category: integrations
+version: 1.0.0
+contributed: 2026-03-01
+contributor: your-memory-repo
+last_updated: 2026-03-01
+contributors:
+  - your-memory-repo
+tags: [mcp, tool-orchestration, composite-tools, token-optimization, typescript]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# MCP Composite Tool Orchestration
+
+## Problem
+
+LLM agents waste 30-70% of their reasoning tokens on sequential tool call chains. Each step requires the model to read the result, reason about next steps, and call the next tool. Common patterns like "search → read result → read another file → synthesize" burn 4 reasoning cycles when the server could do it in 1.
+
+Example token waste for a symbol trace:
+```
+Turn 1: grep "functionName"          → 500 tokens reasoning
+Turn 2: read file_a.ts lines 50-80   → 400 tokens reasoning
+Turn 3: read file_b.ts lines 10-30   → 400 tokens reasoning
+Turn 4: read file_c.ts lines 100-120 → 400 tokens reasoning
+Total: 4 calls, ~1,700 tokens of intermediate reasoning
+```
+
+A composite `trace_references` tool does the same work in 1 call, 0 intermediate reasoning.
+
+## Solution Pattern
+
+Build MCP tools that chain 2-5 related operations server-side, eliminating the LLM reasoning between steps. The server has direct access to resources (filesystem, vector DB, APIs) and can run operations in parallel without round-trip overhead.
+
+**Design principles:**
+
+1. **Identify sequential patterns** — Look for tool call sequences that always appear together (e.g., search → read files, ls → read configs)
+2. **Parallel where possible** — Use `Promise.allSettled()` to run independent operations concurrently
+3. **Dedup results** — Composite tools often query overlapping data; deduplicate before returning
+4. **Return structured Markdown** — Format results so the LLM can reason on them immediately without reformatting
+5. **Fail partially, not totally** — If 3/5 file reads succeed, return those 3 with errors for the 2 failures
+
+## Code Example
+
+### Before — Sequential Tool Calls (4 round trips)
+
+```typescript
+// LLM must reason between each call
+const searchResults = await codebase_search({ query: "auth middleware" });
+// ... LLM reads results, picks files ...
+const file1 = await read_file({ path: searchResults[0].file });
+// ... LLM reads file1, wants another ...
+const file2 = await read_file({ path: searchResults[1].file });
+// ... LLM finally has enough context to answer
+```
+
+### After — Composite Tool (1 round trip)
+
+```typescript
+// search_and_read: search + auto-read top N unique files
+server.tool(
+  'search_and_read',
+  'Semantic search + auto-read full source files of top results.',
+  {
+    query: z.string().min(2).describe('Semantic search query'),
+    project: z.string().optional().describe('Filter by project'),
+    max_files: z.number().int().min(1).max(10).default(3),
+  },
+  async ({ query, project, max_files }) => {
+    // Step 1: Semantic search
+    const queryVec = await embedder.embedQuery(query);
+    const results = await store.search(queryVec, max_files * 3, { project });
+
+    // Step 2: Deduplicate by file, take top N unique
+    const uniqueFiles: string[] = [];
+    const seen = new Set<string>();
+    for (const r of results) {
+      if (!seen.has(r.sourceFile)) {
+        seen.add(r.sourceFile);
+        uniqueFiles.push(r.sourceFile);
+        if (uniqueFiles.length >= max_files) break;
+      }
+    }
+
+    // Step 3: Read all files in parallel
+    const fileContents = await Promise.allSettled(
+      uniqueFiles.map(path => readFile(path, 'utf-8'))
+    );
+
+    // Return combined search results + file contents
+    return formatCombinedResults(results, fileContents);
+  }
+);
+```
+
+## The Five Proven Composite Operations
+
+These patterns were validated on real codebases with measured token savings:
+
+| Composite Tool | Replaces | Round Trips Saved | Token Savings |
+|---|---|---|---|
+| `batch_read` | Sequential file reads | 2-4 | 58% |
+| `multi_search` | Sequential search queries | 2-4 | 62% |
+| `project_overview` | ls + read configs | 3-5 | 72% |
+| `trace_references` | grep + read definition + read usages | 3-6 | 65% |
+| `search_and_read` | search + read top results | 2-3 | 60% |
+
+### batch_read — Read Multiple Files in One Call
+
+```typescript
+export async function batchRead(files: FileSpec[]): Promise<FileReadResult[]> {
+  const results = await Promise.allSettled(
+    files.map(async (spec) => {
+      const raw = await readFile(spec.path, 'utf-8');
+      const lines = raw.split('\n');
+      if (spec.startLine || spec.endLine) {
+        const start = Math.max(0, (spec.startLine || 1) - 1);
+        const end = spec.endLine ? Math.min(spec.endLine, lines.length) : lines.length;
+        return { path: spec.path, content: lines.slice(start, end).join('\n'), lineCount: end - start };
+      }
+      return { path: spec.path, content: raw.slice(0, 500_000), lineCount: lines.length };
+    })
+  );
+  // Return fulfilled results + error info for failures
+  return results.map(r => r.status === 'fulfilled' ? r.value : { path: '', content: '', lineCount: 0, error: 'Read failed' });
+}
+```
+
+### project_overview — Session Start in One Call
+
+```typescript
+// Eliminates the ritual: ls → read package.json → read tsconfig → read .env.example
+export async function projectOverview(directory: string, depth: number, includeConfigs: boolean) {
+  const tree = await buildDirectoryTree(directory, depth);    // Walk dirs, skip node_modules/.git
+  const configs = await readConfigFiles(directory);            // package.json, tsconfig, Dockerfile...
+  const entryPoints = await detectEntryPoints(directory);      // src/index.ts, main.py, server.js...
+  return { directory, tree, configs, entryPoints, stats };
+}
+```
+
+### trace_references — Symbol Definition + All Usages
+
+```typescript
+// Uses dual semantic queries: "symbol definition" + "symbol usage"
+export async function traceReferences(symbol: string, store, embedder, project?) {
+  const [defVec, useVec] = await Promise.all([
+    embedder.embedQuery(`${symbol} definition implementation`),
+    embedder.embedQuery(`${symbol} usage reference call`),
+  ]);
+  const [defs, uses] = await Promise.all([
+    store.search(defVec, 5, { project }),
+    store.search(useVec, 15, { project }),
+  ]);
+  // Match definition with regex patterns (function/class/interface/type/const/def)
+  // Collect usages, deduplicate by file:line, filter to actual mentions
+  return { symbol, definition, usages, totalReferences };
+}
+```
+
+## Implementation Steps
+
+1. **Audit your tool call logs** — identify the 3-5 most common sequential patterns
+2. **Design composite interfaces** — each composite tool maps to one user intent (e.g., "understand this symbol")
+3. **Separate orchestration from server** — put composite logic in an `orchestrator.ts` module, import into MCP server
+4. **Use `Promise.allSettled()`** — never `Promise.all()` for composite operations; partial success is better than total failure
+5. **Format for immediate consumption** — return Markdown with headers, code blocks, and summaries the LLM can use directly
+
+## When to Use
+
+- Building MCP servers where users (LLM agents) repeatedly chain the same tool sequences
+- Semantic search systems where search → read is the dominant access pattern
+- Codebase analysis tools where grep → read → read is common
+- Any MCP server where 3+ of its tools are regularly called in sequence
+
+## When NOT to Use
+
+- Single-purpose tools where each call is truly independent
+- Tools where the intermediate reasoning IS the value (e.g., debugging where each step informs the next hypothesis)
+- Extremely large result sets where the composite response would exceed context limits — keep individual tools for those cases
+
+## Common Mistakes
+
+- **Over-compositing** — don't combine unrelated operations; each composite should map to one user intent
+- **Using `Promise.all()`** — one failure kills everything; use `Promise.allSettled()` and return partial results
+- **No truncation** — composite tools return more data than individual calls; always cap response size
+- **Missing deduplication** — multi_search and trace_references naturally produce overlapping results; dedup by file+line
+- **Blocking on optional data** — if config file reading fails in project_overview, still return the tree
+
+## Related Skills
+
+- [node_mcp_server](../../marketplaces/anthropic-agent-skills/skills/mcp-builder/reference/node_mcp_server.md) - Base MCP server architecture
+- [claude-code-local-mcp-integration](./claude-code-local-mcp-integration.md) - Registering and debugging local MCP servers
+
+## References
+
+- Proven on: your-memory-repo codebase-context MCP server (Feb 2026)
+- Research: Tool Orchestrator MCP analysis of 405+ debug files, 60+ handoffs
+- Token savings validated against sequential tool call baselines