Content
# copilot-studio-code
A local MCP server that gives a Microsoft Copilot Studio agent Claude-Code-style tools against your local filesystem and shell — read, edit, search, and run commands from the Copilot Studio test canvas. Ships with an importable Copilot Studio solution so you can stand up a working agent in minutes.
## Tools exposed
| Tool | Purpose |
|--------------|---------|
| `read_file` | Read a UTF-8 text file. |
| `write_file` | Create or overwrite a file. |
| `edit_file` | Exact-match string replace (unique-match required, or `replace_all=true`). |
| `list_dir` | List entries in a directory. |
| `glob` | Find files matching a glob pattern. |
| `grep` | Regex search across files (skips `node_modules`, `.git`, `dist`). |
| `run_shell` | Execute a shell command (PowerShell on Windows, bash elsewhere). Disabled in `strict` mode. |
## Safety modes (selected at startup)
| Mode | Path jail | `run_shell` |
|------|-----------|-------------|
| `strict` | enforced | **disabled** |
| `moderate` (default) | enforced | enabled, audit-logged |
| `open` | off | enabled, audit-logged |
How the mode is chosen, in order of precedence:
1. `SAFETY` env var (`strict` / `moderate` / `open`)
2. `--safety <mode>` CLI flag
3. Interactive prompt at startup (10s timeout → `moderate`)
All `write_file`, `edit_file`, and `run_shell` calls are appended to `<root>/.copilotstudio-mcp/audit.log`.
## Run it
```powershell
npm install
npm start
```
The server prints something like:
```
copilot-studio-code MCP server
workspace root : E:\Dev\projects\my-project
safety mode : moderate
listening on : http://localhost:8787/mcp
health check : http://localhost:8787/healthz
```
Override the workspace it operates on:
```powershell
$env:WORKSPACE_ROOT = "E:\Dev\some-other-project"; npm start
```
## Wiring it into Copilot Studio
Copilot Studio is cloud-hosted, so it cannot reach `localhost`. Use **Microsoft Dev Tunnels** to expose the server over HTTPS.
### 1. Install and log in to dev tunnels
```powershell
winget install Microsoft.devtunnel
devtunnel user login
```
### 2. Create a persistent tunnel for port 8787
```powershell
devtunnel create copilotstudio-mcp --allow-anonymous
devtunnel port create copilotstudio-mcp -p 8787 --protocol http
devtunnel host copilotstudio-mcp
```
`devtunnel host` prints a public URL like `https://<id>-8787.usw2.devtunnels.ms`. Leave it running.
> Drop `--allow-anonymous` and the tunnel will require an MS account on the Copilot Studio side. Recommended once you have it working.
### 3. Wire the MCP server into a Copilot Studio agent
Two ways: import the prebuilt solution (fastest), or configure an agent manually.
#### Path A — Import the prebuilt solution
The [`solution/`](./solution) folder ships an unmanaged Copilot Studio solution containing a pre-configured agent (generative orchestration on, content moderation low), a custom connector for the MCP server, and a `WorkspaceMCP` topic that surfaces the tools to the planner.
1. Open https://make.powerapps.com → your environment → **Solutions** → **Import solution**.
2. Upload `solution/CopilotStudioCode_1_0_0_0.zip`. Take the defaults through the wizard.
3. Once imported, open the **Workspace MCP** custom connector → **Edit** → on the **General** tab, replace the placeholder host `YOUR-TUNNEL-ID-PORT.YOUR-REGION.devtunnels.ms` with your real dev tunnel host (e.g. `abc123-8787.usw2.devtunnels.ms`). Save → **Update connector**.
4. Open the imported agent and skip to step 4 (test canvas).
> The solution does not include the MCP server itself — that runs locally from this repo. The connector just points at it.
#### Path B — Configure an agent manually
1. Open Copilot Studio → your agent → **Tools** → **+ Add a tool** → **Model Context Protocol**.
2. Server URL: `https://<your-tunnel-id>-8787.usw2.devtunnels.ms/mcp`
3. Authentication: **None** (for the anonymous tunnel) or **Microsoft Entra** (for an authenticated one).
4. Save. Copilot Studio fetches the tool list from `/mcp` and shows the seven tools. Ensure each is enabled on the agent.
5. Settings → **Generative AI** → Orchestration: **Generative**; content moderation: **Low**. Without generative orchestration the planner won't dispatch MCP tools.
### 4. Test it from the test canvas
Open the test canvas and try prompts like:
- "List the files in the workspace root."
- "Read package.json and tell me what scripts are defined."
- "Add a new script called `lint` that runs `tsc --noEmit`."
- "Run `git status` and summarize the result."
The agent picks tools by name from the descriptions in `src/tools.ts` — tighten those descriptions if the agent picks the wrong tool.
## Project layout
```
src/ the MCP server (TypeScript)
index.ts entry: safety prompt + boot
server.ts express + Streamable HTTP MCP transport
tools.ts the seven tool registrations
safety.ts mode definitions
paths.ts workspace-root path jail
audit.ts JSONL audit log
solution/ importable Copilot Studio solution
CopilotStudioCode_1_0_0_0.zip agent + connector + topics (unmanaged)
```
