Skip to content

Commit db96845

Browse files
tdeveretdevere
committed
docs: Add local tool synthesis policy and README updates
- Create comprehensive policy document for local tool synthesis - Add opt-in flags: --enable-local-tool-synthesis and --no-mcp - Document tool scaffold generation workflow - Update README with feature overview (disabled by default) - Emphasize MCP prevention and local-only approach
1 parent 05c4aa8 commit db96845

2 files changed

Lines changed: 265 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,30 @@ copilot-auto --max-iterations 100 --deny-tool "shell(git push)" "Refactor the co
9999

100100
See [AUTO-WRAPPER-README.md](./AUTO-WRAPPER-README.md) for complete documentation.
101101

102+
### Local Tool Synthesis (Experimental, Opt-in)
103+
104+
**⚠️ Disabled by default** - Requires explicit activation
105+
106+
The wrapper supports local tool synthesis for creating custom tools on-demand without external dependencies:
107+
108+
```bash
109+
# Enable local tool synthesis with MCP prevention
110+
copilot-auto --enable-local-tool-synthesis --no-mcp "Build custom tooling"
111+
112+
# Or use environment variables
113+
export COPILOT_LOCAL_TOOL_SYNTHESIS=1
114+
export COPILOT_NO_MCP=1
115+
copilot-auto "Create specialized tools"
116+
```
117+
118+
**Key Points:**
119+
- ❌ **Never uses MCP servers** when `--no-mcp` flag is set
120+
- 📦 **Creates tool scaffolds locally** in `tools/` directory
121+
- 🔒 **Opt-in only** - No behavior change unless explicitly enabled
122+
- 🛡️ **Safe by default** - Scaffolds fail with clear implementation instructions
123+
124+
See [docs/local-tool-synthesis-policy.md](./docs/local-tool-synthesis-policy.md) for full documentation.
125+
102126
## 📢 Feedback and Participation
103127

104128
We're excited to have you join us early in the Copilot CLI journey.

‎docs/local-tool-synthesis-policy.md‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# Local Tool Synthesis Policy
2+
3+
## Overview
4+
5+
This document defines the local tool synthesis policy for the Copilot CLI Auto-Approval Wrapper. This feature enables dynamic tool creation and registration without relying on external services or MCP (Model Context Protocol) servers.
6+
7+
## Non-negotiable: Never Use MCP Servers
8+
9+
**This policy strictly prohibits the use of MCP servers or any remote tool brokers/registries.**
10+
11+
When the MCP prevention flag is enabled (`--no-mcp` or `COPILOT_NO_MCP=1`), the system will:
12+
- NOT enumerate MCP servers
13+
- NOT connect to MCP endpoints
14+
- NOT invoke any MCP-based tools
15+
- Skip all MCP integration code paths
16+
17+
This ensures complete isolation from external tool providers and maintains full local control.
18+
19+
## Local Tool Synthesis by Default (Opt-in)
20+
21+
When enabled via flags or environment variables, the wrapper will automatically scaffold new tools locally when they are requested but not available.
22+
23+
**Important: This feature is DISABLED by default** and must be explicitly opted into via:
24+
- CLI flag: `--enable-local-tool-synthesis`
25+
- Environment variable: `COPILOT_LOCAL_TOOL_SYNTHESIS=1`
26+
27+
### Why Opt-in?
28+
29+
To maintain backward compatibility and avoid changing behavior for existing applications, this feature requires explicit activation. Users must consciously choose to enable local tool synthesis.
30+
31+
## Tool Synthesis Protocol
32+
33+
### Workflow
34+
35+
When a tool is requested that doesn't exist in the local registry:
36+
37+
1. **Detection**: The tool dispatcher detects the missing tool
38+
2. **Check Configuration**: Verify that local tool synthesis is enabled
39+
3. **Scaffold Creation**: Generate a tool skeleton with:
40+
- Tool specification file (`tools/<toolname>/tool.md`)
41+
- Stub implementation (`tools/<toolname>/src/index.js`)
42+
- Registry entry update (`tools/manifest.json`)
43+
4. **Notification**: Inform the user that a scaffold was created
44+
5. **Return**: Return a placeholder result indicating implementation is needed
45+
46+
### File Structure
47+
48+
```
49+
tools/
50+
├── manifest.json # Central registry of all local tools
51+
├── my-custom-tool/
52+
│ ├── tool.md # Tool specification and documentation
53+
│ ├── src/
54+
│ │ └── index.js # Tool implementation
55+
│ └── tests/ # Optional: tool tests
56+
│ └── test.js
57+
```
58+
59+
### Manifest Schema
60+
61+
The `tools/manifest.json` file maintains a registry of all local tools:
62+
63+
```json
64+
{
65+
"version": "1.0.0",
66+
"tools": {
67+
"my-custom-tool": {
68+
"name": "my-custom-tool",
69+
"description": "Description of what this tool does",
70+
"command": "node",
71+
"args": ["tools/my-custom-tool/src/index.js"],
72+
"schema": {
73+
"parameters": {
74+
"type": "object",
75+
"properties": {},
76+
"required": []
77+
}
78+
},
79+
"createdAt": "2026-02-02T17:00:00.000Z",
80+
"status": "scaffold"
81+
}
82+
}
83+
}
84+
```
85+
86+
### Tool Specification Template
87+
88+
Each tool's `tool.md` file contains:
89+
90+
```markdown
91+
# Tool: <toolname>
92+
93+
## Status
94+
**Scaffold** - Implementation needed
95+
96+
## Purpose
97+
[Auto-generated or user-specified description]
98+
99+
## Parameters
100+
[Expected input parameters and their types]
101+
102+
## Implementation Notes
103+
This is a scaffolded tool. To complete implementation:
104+
1. Edit `src/index.js` with actual functionality
105+
2. Add tests in `tests/` directory
106+
3. Update status in `tools/manifest.json` to "implemented"
107+
4. Test thoroughly before use
108+
109+
## Usage Example
110+
[How to invoke this tool once implemented]
111+
```
112+
113+
### Stub Implementation
114+
115+
The generated `src/index.js` stub:
116+
117+
```javascript
118+
#!/usr/bin/env node
119+
120+
/**
121+
* Auto-generated tool scaffold
122+
* Tool: <toolname>
123+
* Created: <timestamp>
124+
*
125+
* TODO: Implement actual functionality
126+
*/
127+
128+
console.error('Tool scaffold created locally. Implement me.');
129+
console.error('Edit: tools/<toolname>/src/index.js');
130+
process.exit(1);
131+
```
132+
133+
## Safety and Idempotency
134+
135+
- **No Overwrites**: Existing tools are never overwritten during scaffold generation
136+
- **Safe Naming**: Tool names are converted to kebab-case for safe filesystem usage
137+
- **Validation**: Tool names must match pattern: `^[a-z][a-z0-9-]*$`
138+
- **Atomic Operations**: Registry updates are atomic to prevent corruption
139+
140+
## Configuration Options
141+
142+
### CLI Flags
143+
144+
- `--enable-local-tool-synthesis` (boolean, default: `false`)
145+
- Enables automatic tool scaffold generation
146+
147+
- `--no-mcp` (boolean, default: `false`)
148+
- Prevents all MCP server usage
149+
- Recommended when using local tool synthesis for complete isolation
150+
151+
### Environment Variables
152+
153+
- `COPILOT_LOCAL_TOOL_SYNTHESIS=1|true|yes|on`
154+
- Enables local tool synthesis (same as CLI flag)
155+
156+
- `COPILOT_NO_MCP=1|true|yes|on`
157+
- Disables MCP (same as CLI flag)
158+
159+
### Precedence
160+
161+
1. Command-line flags (highest priority)
162+
2. Environment variables
163+
3. Configuration file settings
164+
4. Default values (lowest priority)
165+
166+
## Integration with Existing Tools
167+
168+
The local tool synthesis system integrates with the existing wrapper architecture:
169+
170+
1. **Tool Resolution**: Before invoking a tool, check local registry first
171+
2. **Fallback Logic**: If tool not found and synthesis disabled, follow normal error path
172+
3. **No Breaking Changes**: Existing tool invocation patterns remain unchanged
173+
4. **Transparent Operation**: Users without flags enabled see no difference
174+
175+
## Development Workflow
176+
177+
### For Users
178+
179+
1. Enable local tool synthesis: `copilot-auto --enable-local-tool-synthesis --no-mcp`
180+
2. Request functionality that requires a new tool
181+
3. System creates scaffold automatically
182+
4. Implement the tool in `tools/<toolname>/src/index.js`
183+
5. Test the implementation
184+
6. Tool is now available for use
185+
186+
### For Developers
187+
188+
1. Add tests for scaffold generation in test suite
189+
2. Ensure manifest updates are atomic
190+
3. Validate tool name safety
191+
4. Test with and without synthesis enabled
192+
5. Verify no MCP connections when flag is set
193+
194+
## Security Considerations
195+
196+
- **Local Only**: No network calls for tool discovery or execution
197+
- **Explicit Activation**: Users must opt in explicitly
198+
- **No Auto-Execution**: Scaffolded tools fail safely with clear messages
199+
- **File System Safety**: All file operations use safe path handling
200+
- **Validation**: Tool names and paths are validated before creation
201+
202+
## Future Enhancements
203+
204+
Potential future additions (not in initial implementation):
205+
- Tool versioning and updates
206+
- Shared tool libraries
207+
- Template customization
208+
- Auto-implementation hints based on description
209+
- Testing framework integration
210+
- Tool documentation generation
211+
212+
## Compatibility
213+
214+
- **Minimum Node.js**: 22.0.0
215+
- **Operating Systems**: Linux, macOS, Windows
216+
- **Backward Compatible**: Default behavior unchanged
217+
- **Forward Compatible**: Registry format designed for extension
218+
219+
## Examples
220+
221+
### Enable both flags together (recommended)
222+
```bash
223+
copilot-auto --enable-local-tool-synthesis --no-mcp "Create a tool to parse JSON"
224+
```
225+
226+
### Using environment variables
227+
```bash
228+
export COPILOT_LOCAL_TOOL_SYNTHESIS=1
229+
export COPILOT_NO_MCP=1
230+
copilot-auto "Process this data"
231+
```
232+
233+
### Default behavior (no change)
234+
```bash
235+
copilot-auto "Normal usage without synthesis"
236+
# No scaffolding occurs, normal error handling applies
237+
```
238+
239+
## Support and Feedback
240+
241+
This is an experimental feature. Please report issues and provide feedback to help us improve the local tool synthesis experience.

0 commit comments

Comments
 (0)