@njuptlzf/mcp-adapter 2.29.0-0.0.1

package/skills/mcp-adapter/references/verify.md

@@ -0,0 +1,157 @@
+# Phase 3 Reference: Verify Deployment
+
+> **Called from**: `skills/mcp-adapter/SKILL.md` Phase 3
+> **Path resolution**: See [resolver.md](resolver.md) — agent discovery + Host × Target matrix
+
+Runs the full mcp-adapter integration test matrix to confirm deployment works.
+
+## Quick Verification
+
+```bash
+npm run verify:deploy -- --agent universal-mcp
+```
+
+Checks: adapter creation → context → config loading → tool registration → session lifecycle.
+Pass: `✅ Universal MCP verification passed`.
+
+## Full Test Matrix
+
+### Pre-flight
+
+```bash
+mkdir -p tests/reports
+npm run test:prebuild  # build visualizer dist/
+```
+
+### Phase 1: MockAgent Compatibility (Section 4)
+
+```bash
+npx vitest run tests/compatibility/ --reporter=verbose
+```
+
+**Pass**: 44/44 (40 server + 4 contract).
+
+### Phase 2: Token Benchmark (Section 5)
+
+```bash
+npx tsx tests/token-benchmark/run-baseline.ts
+npx tsx tests/token-benchmark/run-adapter.ts
+npx tsx tests/token-benchmark/report.ts
+```
+
+**Pass**: Proxy tool ≤ 300 tokens; 10-server savings ≥ 95%.
+
+### Phase 3: Conversation Cost Simulation (Section 5B)
+
+```bash
+npx tsx tests/token-benchmark/run-conversation-sim.ts
+```
+
+Skip if file missing (conditional guard).
+
+### Phase 4: Per-Path Verification (Section 6)
+
+#### Step 0 — Capability Gate
+
+Uses the Host × Target matrix from [resolver.md](resolver.md#host--target-matrix):
+
+| `mcp` in host tools? | `^<server>_` prefix? | `^mcp_` SDK bridge? | Host mode |
+|----------------------|---------------------|---------------------|-----------|
+| yes | any | any | Full mcp proxy |
+| no | yes | any | directTools |
+| no | no | no | SDK_DIRECT (spawn required) |
+
+#### Step 1 — Path verification
+
+Read [resolver.md](resolver.md) and execute:
+- Path A: `adapter.getAllTools()` includes `mcp`
+- Path B: individual tools with server prefix
+- Path C: SDK_DIRECT fallback
+
+#### Step 2 — Proxy mode unit tests
+
+```bash
+npx vitest run __tests__/proxy-modes-discovery.test.ts __tests__/proxy-modes-auto-auth.test.ts __tests__/proxy-modes-ui-messages.test.ts --reporter=verbose
+```
+
+#### Step 3 — directTools unit + integration
+
+```bash
+npx vitest run __tests__/direct-tools.test.ts __tests__/direct-tools-auto-auth.test.ts
+npx vitest run tests/smoke/e2e-direct-tools.test.ts
+```
+
+#### Step 4 — E2E tests
+
+```bash
+npx vitest run tests/smoke/e2e-all-servers.test.ts --reporter=verbose
+```
+
+**Pass**: 25/25.
+
+#### Step 5 — Protocol Forwarder Tests
+
+```bash
+# ProtocolSamplingForwarder unit tests (sampling forwarding via server.createMessage)
+npx vitest run __tests__/protocol-sampling-forwarder.test.ts --reporter=verbose
+
+# ProtocolElicitationForwarder unit tests (elicitation forwarding via server.elicitInput)
+npx vitest run __tests__/protocol-elicitation-forwarder.test.ts --reporter=verbose
+
+# Universal MCP server E2E tests (subprocess + real MCP Client)
+npx vitest run __tests__/mcp-server-e2e.test.ts --reporter=verbose
+```
+
+#### Step 6 — Adapter Integration Tests (Host × Target × Mode)
+
+The three dimensions are independent:
+
+| Dimension | Values | Default |
+|-----------|--------|---------|
+| Host | Current agent, Universal MCP, … | Current agent |
+| Target | universal-mcp | universal-mcp |
+| Mode | in-process / spawn / mock | in-process |
+
+**Step 6a — Discover adapters**:
+
+```bash
+echo "=== Discovered adapters ==="
+grep -B1 -A5 "id:" interfaces/agent-api.ts | grep -E "(id:|displayName:|capabilities:)" | head -40
+```
+
+**Step 6b — User selection**: AskUserQuestion for Host/Target/Mode (3D matrix).
+
+**Step 6c — Run contract tests**:
+
+```bash
+npx vitest run __tests__/adapter-contract.test.ts --reporter=verbose
+```
+
+**Step 6d — Deployment wiring verification**:
+
+```bash
+npm run verify:deploy                      # all harnessed adapters
+npm run verify:deploy -- --agent universal-mcp  # universal MCP server
+```
+
+### Report
+
+`tests/reports/mcp-adapter-test-report.md` — auto-generated by matrix reporter.
+Never edit by hand.
+
+## One-Screen Summary
+
+```
+=== mcp-adapter Test Results ===
+Section 4 (MockAgent):        ✅ 44/44
+Section 5 (Token Bench):      ✅ 94% savings
+Section 5B (Conversation):    ✅/⚠️/SKIP
+Proxy Unit Tests:             ✅ N/N
+DirectTools Unit+Integration: ✅ 24/24
+Section 6 (E2E):              ✅ 25/25
+Protocol Forwarders:          ✅ N/N
+Adapter Integration (Step 6): ✅ N/N
+Capability Gate:              Host=<current> × Target=<selected>
+
+Verdict: 🟢 ALL PASS
+```

package/skills/mcp-scripting/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: mcp-scripting
+description: Write mcpScript JavaScript for discovering, inspecting, and calling MCP tools.
+---
+
+# MCP scripting
+
+For multi-call MCP work, write ordinary JavaScript with loops, filtering, chaining, fan-out, or other logic between calls. Run that source with `mcpScript`; it is the primary MCP orchestration surface. For a single MCP search, describe, status check, auth action, or tool call, use `mcp` instead.
+
+Write the source naturally, then pass it as `mcpScript`'s `code` argument:
+
+```js
+const { items } = await tools.search({ query: "search issues", server: "github" });
+const candidate = items[0];
+if (!candidate) return { error: "No matching tool" };
+
+const details = await tools.describe({ path: candidate.path });
+if (details.error) return details;
+
+const result = await tools.call(details.path, { query: "is:open label:bug" });
+if (!result.ok) return result;
+emit({ tool: details.path, completed: true });
+return result.data;
+```
+
+## Workflow
+
+1. Find candidate tools with `await tools.search({ query, server?, limit?, offset? })`.
+2. Inspect the exact returned path with `await tools.describe({ path })`.
+3. Call it with `tools.call(path, args)`.
+
+Calls resolve to `{ ok: true, data }` or `{ ok: false, error }`; handle failed calls instead of expecting them to stop the script. `emit(value)` adds user-visible output before the final `return` value. `console` output is captured too.
+
+`tools` is a non-enumerable proxy: `Object.keys(tools)` throws. Always use `tools.search` for discovery. When a known flat path is a valid identifier, direct calls such as `tools.github_search_issues(args)` are supported; use bracket syntax for hyphenated names: `tools["server_tool-name"](args)`. `search`, `call`, `describe`, and promise/serialization names (`then`, `catch`, `finally`, `toJSON`, `toString`, `valueOf`) are reserved on the proxy; if a flat path collides with one, call it via `tools.call("exact-path", args)`.
+
+`tools.search` and `tools.describe` are asynchronous and must be awaited. The default script timeout is 30 seconds; the worker is terminated at the deadline, including for infinite loops. Every invocation still uses normal lazy connection, authentication, output guarding, and approval gates. Result details contain a concise `calls` trace with every search, describe, and call operation; each entry includes its query or path, outcome, and duration.
+
+Use plain JavaScript loops and Promise utilities for composition. Fluent helpers such as `tools.find(...).one()`, `tools.parallel(...)`, and `tools.retry(...)` are not provided.

package/skills/resolve-conflicts/SKILL.md

@@ -0,0 +1,482 @@
+---
+name: resolve-conflicts
+description: Use this skill immediately when the user mentions merge conflicts that need to be resolved. Do not attempt to resolve conflicts directly - invoke this skill first. This skill specializes in providing a structured framework for merging imports, tests, lock files (regeneration), configuration files, and handling deleted-but-modified files with backup and analysis.
+---
+
+# Git Conflict Resolution
+
+Resolve Git merge conflicts by intelligently combining changes from both branches while preserving the intent of both changes. This skill follows a plan-first approach: assess conflicts, create a detailed resolution plan, get approval, then execute.
+
+## Core Principles
+
+1. **Plan Before Executing**: Always create a structured resolution plan and get user approval before making changes
+2. **Prefer Both Changes**: Default to keeping both changes unless they directly contradict
+3. **Merge, Don't Choose**: Especially for imports, tests, and configuration
+4. **Regenerate Generated Files**: Never manually merge generated files - always regenerate them from their sources
+5. **Backup Before Resolving**: For deleted-modified files, create backups first
+6. **Validate with Tests**: Always run tests after resolution
+7. **Explain All Resolutions**: For each conflict resolved, provide a one-line explanation of the resolution strategy
+8. **Ask When Unclear**: When the correct resolution isn't clear from the diff, present options to the user and ask for their choice
+
+## Workflow
+
+### Step 1: Assess the Conflict Situation
+
+Run initial checks to understand the conflict scope:
+
+```bash
+git status
+```
+
+Identify and categorize all conflicted files:
+
+- Regular file conflicts (both modified)
+- Deleted-modified conflicts (one deleted, one modified)
+- Generated file conflicts (lock files, build artifacts, generated code)
+- Test file conflicts
+- Import/configuration conflicts
+- Binary file conflicts
+
+For each conflicted file, gather information:
+
+- File type and purpose
+- Nature of the conflict (content, deletion, type change)
+- Scope of changes (lines changed, sections affected)
+- Whether the file is generated or hand-written
+
+### Step 2: Create Merge Resolution Plan
+
+Based on the assessment, create a structured plan before resolving any conflicts. Present the plan in the following markdown format:
+
+```markdown
+## Merge Resolution Plan
+
+### Conflict Summary
+
+- **Total conflicted files**: [N]
+- **Deleted-modified conflicts**: [N]
+- **Generated files**: [N]
+- **Regular conflicts**: [N]
+
+### Resolution Strategy by File
+
+#### 1. [File Path]
+
+**Conflict Type**: [deleted-modified / generated / imports / tests / code logic / config / struct / binary]
+**Strategy**: [Brief description of resolution approach]
+**Rationale**: [Why this strategy is appropriate]
+**Risk**: [Low/Medium/High] - [Brief risk description]
+**Action Items**:
+
+- [ ] [Specific action 1]
+- [ ] [Specific action 2]
+
+#### 2. [File Path]
+
+...
+
+### Execution Order
+
+1. **Phase 1: Deleted-Modified Files** - Handle deletions and backups first
+2. **Phase 2: Generated Files** - Regenerate from source
+3. **Phase 3: Low-Risk Merges** - Imports, tests, documentation
+4. **Phase 4: High-Risk Merges** - Code logic, configuration, structs
+5. **Phase 5: Validation** - Compile, test, verify
+
+### Questions/Decisions Needed
+
+- [ ] **[File/Decision]**: [Question for user] (Options: 1, 2, 3)
+
+### Validation Steps
+
+- [ ] Run conflict validation script
+- [ ] Compile project
+- [ ] Run test suite
+- [ ] Manual verification of high-risk changes
+```
+
+**Present this plan to the user** and wait for their approval before proceeding with resolution. If there are any unclear conflicts where you need user input, list them in the "Questions/Decisions Needed" section.
+
+**For a complete example plan**, see `references/sample-plan.md`.
+
+### Step 3: Handle Deleted-Modified Files
+
+**Execute this phase only after the plan is approved.**
+
+If there are deleted-but-modified files (status: DU, UD, DD, UA, AU):
+
+```bash
+.forge/skills/resolve-conflicts/scripts/handle-deleted-modified.sh
+```
+
+This script will:
+
+- Create timestamped backups of modified content
+- Analyze potential relocation targets
+- Generate analysis reports for each file
+- Automatically resolve the deletion status
+
+Review the backup directory and analysis files to understand where changes should be applied.
+
+### Step 4: Execute Resolution Plan
+
+**Follow the execution order defined in your plan.** For each conflicted file, apply the appropriate resolution pattern according to your plan. **For every conflict you resolve, provide a one-line explanation** of how you're resolving it.
+
+As you complete each action item in your plan, mark it as done and report progress to the user.
+
+#### When Resolution is Unclear
+
+When you cannot determine the correct resolution from the diff alone (these should already be listed in your plan's "Questions/Decisions Needed" section):
+
+1. **Present the conflict** to the user with the conflicting code from both sides
+2. **Provide numbered options** for resolution (Option 1, Option 2, etc.)
+3. **Explain each option** clearly with what it would do
+4. **Ask the user to choose** an option number or provide additional information
+5. **Remember their choice** and apply similar reasoning to subsequent related conflicts
+
+**Example interaction:**
+
+```
+I found a conflict in src/main.rs where both branches modify the `calculate_price` function:
+
+<<<<<<< HEAD (Current Branch)
+fn calculate_price(item: &Item) -> f64 {
+    item.base_price * (1.0 + item.tax_rate)
+}
+=======
+fn calculate_price(item: &Item) -> f64 {
+    item.base_price + item.tax_amount
+}
+>>>>>>> feature-branch (Incoming Branch)
+
+I'm not sure which calculation is correct. Please select an option:
+
+**Option 1**: Keep current branch (multiplies base_price by tax_rate)
+**Option 2**: Keep incoming branch (adds tax_amount to base_price)
+**Option 3**: Keep both approaches with a new parameter
+**Option 4**: Provide more context to help me decide
+
+Please respond with "Option 1", "Option 2", "Option 3", or "Option 4", or provide additional information.
+```
+
+Once the user responds, apply their decision and similar logic to related conflicts.
+
+#### Resolution Patterns
+
+For each conflicted file, apply the appropriate resolution pattern:
+
+#### Imports/Dependencies
+
+**Goal**: Merge all unique imports from both branches.
+
+**One-line explanation**: "Merging imports by combining unique imports from both branches, removing duplicates, and grouping by module."
+
+Read `references/patterns.md` section "Import Conflicts" for detailed examples.
+
+**Quick approach:**
+
+1. Extract all imports from both sides
+2. Remove duplicates
+3. Group by module/package
+4. Follow language-specific style (alphabetize, group std/external/internal)
+
+#### Tests
+
+**Goal**: Include all test cases and test data from both branches.
+
+**One-line explanation**: "Merging tests by including all test cases from both branches, combining fixtures, and renaming if necessary to avoid conflicts."
+
+Read `references/patterns.md` section "Test Conflicts" for detailed examples.
+
+**Quick approach:**
+
+1. Keep all test functions unless they test the exact same thing
+2. Merge test fixtures and setup functions
+3. Combine assertions from both sides
+4. If test names conflict but test different behaviors, rename to clarify
+
+#### Generated Files
+
+**Goal**: Regenerate any generated files to include changes from both branches.
+
+**One-line explanation**: "Resolving generated file by regenerating it from source files to incorporate changes from both branches."
+
+**Recognition**: A file is generated if it:
+
+- Is produced by a build tool, compiler, or code generator
+- Has a source file or configuration that defines it
+- Contains headers/comments indicating it's auto-generated
+- Is listed in `.gitattributes` as generated
+- Common examples: lock files, protobuf outputs, GraphQL schema files, compiled assets, auto-generated docs
+
+**Approach:**
+
+1. **Identify the generation source**: Determine what command or tool generates the file
+2. **Choose either version** temporarily (doesn't matter which):
+
+   ```bash
+   git checkout --ours <generated-file>    # or --theirs
+   ```
+
+3. **Regenerate from source**: Run the appropriate generation command:
+
+   ```bash
+   # Package manager lock files
+   cargo update                       # for Cargo.lock
+   npm install                        # for package-lock.json
+   yarn install                       # for yarn.lock
+   bundle install                     # for Gemfile.lock
+   poetry lock --no-update            # for poetry.lock
+
+   # Code generation
+   protoc ...                         # for protobuf files
+   graphql-codegen                    # for GraphQL generated code
+   make generate                      # for Makefile-based generation
+   npm run generate                   # for npm script-based generation
+
+   # Build artifacts
+   npm run build                      # for compiled/bundled assets
+   cargo build                        # for Rust build artifacts
+   ```
+
+4. **Stage the regenerated file**:
+   ```bash
+   git add <generated-file>
+   ```
+
+**When unsure if a file is generated**: Check for auto-generation markers in the file header, or ask the user if you should regenerate or manually merge the file.
+
+#### Configuration Files
+
+**Goal**: Merge configuration values from both branches.
+
+**One-line explanation**: "Merging configuration by including all keys from both branches and choosing appropriate values for conflicts."
+
+Read `references/patterns.md` section "Configuration File Conflicts" for detailed examples.
+
+**Quick approach:**
+
+1. Include all keys from both sides
+2. For conflicting values, choose based on:
+   - Newer/more recent value
+   - Safer/more conservative value
+   - Production requirements
+3. Document choice in commit message
+
+**When unclear**: Ask the user which configuration value to prefer (current vs incoming)
+
+#### Code Logic
+
+**Goal**: Understand intent of both changes and combine if possible.
+
+**One-line explanation**: "Resolving code logic by analyzing intent: merging if changes are orthogonal, or choosing one approach if they conflict."
+
+Read `references/patterns.md` section "Code Logic Conflicts" for detailed examples.
+
+**Quick approach:**
+
+1. Analyze what each branch is trying to achieve
+2. If changes are orthogonal (different concerns), merge both
+3. If changes conflict (same concern, different approach):
+   - Review commit messages/PRs for context
+   - Choose the approach that matches requirements
+   - Test both approaches if unclear
+   - Document the decision
+
+**When unclear**: Present both approaches as options to the user with context about what each does
+
+#### Struct/Type Definitions
+
+**Goal**: Include all fields from both branches.
+
+**One-line explanation**: "Merging struct by including all fields from both branches and choosing appropriate types for any conflicting field definitions."
+
+**Quick approach:**
+
+1. Merge all fields
+2. If field types conflict, analyze which is more appropriate
+3. Fix all compilation errors from updated struct
+4. Update tests to use new fields
+
+**When unclear**: Ask the user which type definition is correct if field types conflict
+
+### Step 5: Validate Resolution
+
+After completing all resolution phases in your plan, validate that all conflicts are resolved:
+
+```bash
+.forge/skills/resolve-conflicts/scripts/validate-conflicts.sh
+```
+
+This script checks for:
+
+- Remaining conflict markers (<<<<<<<, =======, >>>>>>>)
+- Unmerged paths in git status
+- Deleted-modified conflicts
+- Merge state files
+
+### Step 6: Compile and Test
+
+Build and test to ensure the resolution is correct (as defined in your plan's validation steps):
+
+```bash
+# For Rust projects
+cargo test
+
+# For other projects, use appropriate test command
+# npm test
+# pytest
+# etc.
+```
+
+If tests fail:
+
+1. Review the failure - is it from merged code or conflict resolution?
+2. Check if both branches' tests pass individually
+3. Fix integration issues between the merged changes
+4. Re-run tests until all pass
+
+### Step 7: Finalize
+
+Once all conflicts are resolved and tests pass, review your completed plan and commit:
+
+```bash
+# Review the changes
+git diff --cached
+
+# Commit with descriptive message that references the plan
+git commit -m "Resolve merge conflicts: [describe key decisions]
+
+Executed merge resolution plan:
+- [Phase 1 summary]
+- [Phase 2 summary]
+- [Phase 3+ summaries]
+
+Key decisions:
+- Merged imports from both branches
+- Combined test cases
+- Regenerated lock files
+- [other significant decisions from plan]
+
+Co-Authored-By: ForgeCode <noreply@forgecode.dev>"
+```
+
+## Decision Tracking
+
+When you ask the user to choose between options, track their decision and apply similar reasoning to subsequent conflicts:
+
+**Example scenario:**
+
+1. First conflict: User chooses Option 1 (prefer current branch's validation logic)
+2. Second similar conflict: Apply the same reasoning (prefer current branch's validation approach)
+3. Mention: "Resolving by keeping current branch's approach (consistent with your earlier choice)"
+
+**Key principles:**
+
+- Remember user preferences within the same conflict resolution session
+- Apply consistent patterns when conflicts are similar
+- Mention the consistency: "Following the same pattern as before..."
+- Ask again if a new conflict is sufficiently different from previous ones
+
+## Common Patterns Reference
+
+For detailed resolution patterns, read:
+
+- `references/patterns.md` - Comprehensive examples for all conflict types
+
+**Quick pattern lookup:**
+
+- **Imports**: Combine all unique imports, group by module
+- **Tests**: Keep all tests unless identical, merge fixtures
+- **Generated files**: Choose either version, regenerate from source
+- **Config**: Merge all keys, choose newer/safer values for conflicts
+- **Code**: Analyze intent, merge if orthogonal, choose one if conflicting
+- **Structs**: Include all fields from both branches
+- **Docs**: Combine all documentation sections
+
+## Special Scenarios
+
+### Binary Files in Conflict
+
+Binary files cannot be merged. Choose one version:
+
+```bash
+git checkout --ours path/to/binary    # keep our version
+# or
+git checkout --theirs path/to/binary  # keep their version
+```
+
+### Mass Rename/Refactoring Conflicts
+
+If one branch renamed/refactored many files while another modified them:
+
+1. Accept the rename/refactoring (structural change)
+2. Apply the modifications to the new structure
+3. Use backups from `handle-deleted-modified.sh` to guide the application
+
+### Submodule Conflicts
+
+```bash
+# Check submodule status
+git submodule status
+
+# Update to the correct commit
+cd path/to/submodule
+git checkout <desired-commit>
+cd ../..
+git add path/to/submodule
+```
+
+## Troubleshooting
+
+### "Both Added" Conflicts (AA)
+
+Both branches added a new file with the same name but different content:
+
+1. Review both versions
+2. If they serve the same purpose, merge their content
+3. If they serve different purposes, rename one
+
+### Whitespace-Only Conflicts
+
+If conflicts are only whitespace differences:
+
+```bash
+git merge -Xignore-space-change <branch>
+```
+
+### Persistent Conflict Markers
+
+If validation shows conflict markers but you think you resolved them:
+
+1. Search for the exact marker strings: `git grep -n "<<<<<<< HEAD"`
+2. Some markers might be in strings or comments - resolve those too
+3. Check for hidden characters or encoding issues
+
+### Tests Fail After Resolution
+
+1. Test each branch individually to confirm they pass
+2. The failure is likely from interaction between the merged changes
+3. Debug the interaction issue, not the individual changes
+4. Update code to make both changes work together
+
+## Quick Reference Card
+
+| Conflict Type    | Strategy                                | One-line Explanation Template                                                                                    |
+| ---------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Imports          | Merge all, deduplicate, group by module | "Merging imports by combining unique imports from both branches and grouping by module"                          |
+| Tests            | Keep all, merge fixtures                | "Including all test cases from both branches and combining test fixtures"                                        |
+| Generated files  | Regenerate from source                  | "Regenerating [file] from source to include changes from both branches"                                          |
+| Config           | Merge keys, choose newer values         | "Merging all config keys and choosing [current/incoming] value for [key]"                                        |
+| Code logic       | Analyze intent, merge if orthogonal     | "Merging both changes as they address different concerns" OR "Choosing [current/incoming] approach for [reason]" |
+| Structs          | Include all fields                      | "Including all fields from both branches in struct definition"                                                   |
+| Docs             | Combine all sections                    | "Combining documentation from both branches"                                                                     |
+| Deleted-modified | Backup, analyze, apply to new location  | "Applying modifications to new location after file was moved/renamed"                                            |
+| Binary files     | Choose one version                      | "Keeping [current/incoming] version of binary file"                                                              |
+
+**Remember:**
+
+- Always provide a one-line explanation for each conflict resolution
+- When unclear, present numbered options to the user
+- Track user decisions and apply consistently to similar conflicts
+- The goal is to preserve the intent and functionality of both branches while creating a cohesive merged result