AWB MCP

AWB MCP is an MCP server that helps you turn any repository into an agentic-ready project. It runs over the Model Context Protocol (MCP), so you can use it from VS Code, or any MCP-capable client. No API keys are required the server talks to your editor over standard input/output.

What’s in this project

• MCP server (src/server.ts) - Starts the server and registers the AWB tool with the MCP SDK (stdio transport).
• Single tool: awb_bootstrap - Computes a plan of file operations (create / update / skip) for bootstrapping an agentic repo, and can apply that plan to disk (atomic, idempotent).
• Bootstrap logic (src/tools/) - Plan computation (planBootstrap.ts), application (applyBootstrap.ts), template loading (loadTemplates.ts), path validation, and baseline/overwrite rules.
• Templates (src/templates/) - Files that get created or updated when you run the bootstrap:
  • AGENTS.md - Repo-level guidance for agents (e.g. “use repo scripts, write tests, avoid destructive commands”).
  • .github/copilot-instructions.md - Copilot/Cursor instructions (optionally with a custom section filled via the client’s LLM when sampling is available).
  • .github/agents/ - Agent definitions (e.g. code-review, debug) and a readme describing them.
  • .github/prompts/ - Planner, generator, and implementer prompts for a three-stage workflow (plan → implementation doc → execution), plus a readme.
  • .github/instructions/ - Stack- or tool-specific instructions (e.g. Angular).

Disclaimer: The prompts, agents, and instructions shipped in this project’s templates are derived from the awesome-copilot repository. They are included here for bootstrap convenience; credit and upstream sources belong to that project.

The server never overwrites your content unless a file is under AWB management (contains <!-- AWB MANAGED BEGIN --> and <!-- AWB MANAGED END -->) or you explicitly allow overwrite via options.

Install

• Node.js: 18 or later (see engines in package.json).

• Global install (recommended so the awb-mcp command is on your PATH):

  npm i -g @kamkom/awb-mcp

• Without installing (run via npx):

  npx @kamkom/awb-mcp

Set up MCP in VS Code

1. Install the server (global or use npx as above).

2. Open your MCP config in VS Code:

   • Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → MCP: Open User Configuration (for all workspaces),
   • or create/edit .vscode/mcp.json in your project for workspace-only config.

3. Add the AWB server in the servers section.

   If you installed globally (recommended):

   {
     "servers": {
       "awb-mcp": {
         "type": "stdio",
         "command": "awb-mcp"
       }
     }
   }

   If you use npx (no global install):

   {
     "servers": {
       "awb-mcp": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@kamkom/awb-mcp"]
       }
     }
   }

4. Save the file. When you use Copilot chat, VS Code may ask you to trust the MCP server the first time-approve it to enable the tool.

5. In Chat, you can ask the AI to run the bootstrap (e.g. “Run awb_bootstrap in dry-run for this project” or “Run awb_bootstrap and apply the plan”). The awb_bootstrap tool will appear when the server is connected.

Tip: You can also run MCP: Add Server from the Command Palette and choose a stdio server, then enter the command (and args if using npx).

Using the tool

• awb_bootstrap - Bootstraps an agentic-ready repo: computes a plan and optionally applies it.
  • dryRun: true - Returns the plan only (no files written). Use this to preview changes.
  • dryRun: false (default) - Computes the plan and applies it to disk.

Sample prompts (run in Chat with MCP connected)

Copy-paste these into VS Code Copilot Chat or Cursor chat (ensure the AWB MCP server is connected and the tool is enabled):

| Goal | Prompt | | ------------------------ | --------------------------------------------------------------------------------------------------------- | | Preview only | Run awb_bootstrap in dry-run mode for the current project so I can review the plan before applying. | | Apply bootstrap | Run awb_bootstrap for this repo and apply the plan to disk. | | Preview + path | Call awb_bootstrap with dryRun true and rootPath set to the current workspace folder; show me the plan. | | Apply with overwrite | Run awb_bootstrap and apply the plan, allowing overwrite of .github/copilot-instructions.md. | | Safe first run | Use the awb_bootstrap tool in dry-run first. If the plan looks good, run it again and apply. |

Options (optional)

• overwritePolicy - "skip" (never overwrite), "managed-only" (default; only overwrite files with AWB managed blocks), "overwrite" (allow overwriting any file in the plan).
• overwritePaths - Array of paths you explicitly allow to be overwritten (e.g. [".github/copilot-instructions.md"]).
• mode - "static" or "prompt" for how templates are used.
• includeReadmeProposal - Include a README proposal in the plan when applicable.

When the client supports sampling (e.g. Cursor, VS Code with a sampling-capable host), the server can request generated content for the custom section of .github/copilot-instructions.md from the client’s LLM; otherwise that section is left empty.

Platforms

• Windows and macOS - Primary supported platforms.
• Linux - Best-effort for v0.1; Linux-only issues may not be prioritized in this milestone.

Development

npm install
npm run build    # compile and copy templates to dist; chmod +x dist/server.js
npm run start    # run with tsx: npx tsx src/server.ts
npm run dev      # watch mode
npm run test     # build + smoke and bootstrap tests

License

ISC