# VA Form Generation MCP Server
**External MCP server for VA form generation automation** - completely separate from the VA codebase, works with any vets-website workspace.
## 🎯 Purpose
This MCP server provides tools and resources for auditing and fixing scaffolded VA forms to ensure they follow 21P-601 best practices and VA.gov content standards.
**Key Benefits:**
- ✅ **External** - Lives outside VA repo, no code review needed
- ✅ **Reusable** - Works with ANY vets-website workspace
- ✅ **Team-friendly** - Share across your entire team
- ✅ **Version controlled** - Track improvements separately
---
## 🚀 Quick Start
### 1. Install
```bash
cd ~/va-form-generation-mcp
npm install
```
### 2. Configure Your Claude Environment
Choose the platform(s) you use:
#### 🖥️ Claude Desktop
Add to your `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"va-form-generation": {
"command": "node",
"args": [
"/Users/YOUR_USERNAME/va-form-generation-mcp/index.js"
]
}
}
}
```
**Replace `YOUR_USERNAME`** with your actual username!
**Then restart Claude Desktop** - the MCP server will automatically connect.
---
#### 💻 Claude Code (VS Code Extension)
Create or update `.mcp.json` in your **vets-website workspace root**:
```json
{
"mcpServers": {
"va-form-generation": {
"command": "node",
"args": ["/Users/YOUR_USERNAME/va-form-generation-mcp/index.js"]
}
}
}
```
**Also update** `.claude/settings.local.json` to enable the MCP server:
```json
{
"permissions": {
"allow": [
"Read(//Users/YOUR_USERNAME/va-form-generation-mcp/**)"
]
},
"enableAllProjectMcpServers": true
}
```
**Then reload your VS Code window** - Claude Code will detect and load the MCP server.
---
#### 🔍 Cursor (Claude Code in Cursor)
Same as Claude Code above - create `.mcp.json` in your workspace root and update `.claude/settings.local.json`.
**Then reload Cursor** to activate the MCP server.
---
#### 💬 ChatGPT
ChatGPT does not currently support MCP servers. However, you can:
1. Copy the templates from `~/va-form-generation-mcp/templates/`
2. Paste them directly into ChatGPT conversations
3. Or use GPT Actions (requires custom GPT with API access)
---
### 3. Verify Setup
In Claude Desktop, Claude Code, or Cursor:
```
Show me all available tools from the va-form-generation MCP server
```
You should see 5 tools listed.
### 4. Use It!
```
Use the va-form-generation MCP server to audit form 21p-0516 in /Users/aponce/Workspaces/vets-website
```
---
## 🛠️ Available Tools
### `audit_form`
Generate comprehensive audit report for a scaffolded form.
**Usage:**
```
Audit form 21p-0516 using the MCP server
Workspace: /Users/aponce/Workspaces/vets-website
```
**Returns:**
- Form information
- Agent execution plan
- Expected fixes
- Quick start commands
---
### `get_agent_prompt`
Get customized prompt for a specific agent (1-4).
**Usage:**
```
Get Agent 2 prompt for form 21p-0516
```
**Returns:**
- Specialized prompt for that agent
- Customized with form-specific paths
- Ready to execute
---
### `validate_form`
Run validation checks (schema, syntax, apostrophes, imports).
**Usage:**
```
Validate form at /path/to/form checking schema and apostrophes
```
**Returns:**
- Bash commands to run validation
- Expected issues to find
---
### `get_fix_reference`
Get quick reference for common fixes.
**Usage:**
```
Show me the yesNoUI fix reference
```
**Options:**
- `yesNoUI` - How to fix yesNoUI patterns
- `radioSchema` - How to fix radioSchema calls
- `apostrophes` - How to fix apostrophe syntax
- `transformers` - How to fix submit/prefill transformers
- `fullNamePath` - How to add fullNamePath (critical!)
- `all` - Show all fixes
---
### `generate_orchestration_prompt`
Generate the complete orchestration prompt to launch all 4 agents.
**Usage:**
```
Generate orchestration prompt for form 21p-0516
```
**Returns:**
- Complete prompt to launch all 4 agents
- Phase-by-phase execution plan
- Expected results
---
## 📚 Available Resources
### `checklist://master`
Complete master checklist for form generation.
### `template://agent-1` through `template://agent-4`
Specialized prompts for each of the 4 agents.
### `reference://fixes`
Before/after examples for all 16 fixes.
---
## 🎯 Typical Workflow
### Option 1: Full Automation
```
Use the va-form-generation MCP server to:
1. Audit form 21p-0516 in /Users/aponce/Workspaces/vets-website
2. Generate the orchestration prompt
3. Execute all 4 agents
```
### Option 2: Step by Step
```
1. Audit form 21p-0516 using MCP server
2. Get Agent 1 prompt from MCP server
3. Get Agent 2 prompt from MCP server
4. Get Agent 3 prompt from MCP server
5. Get Agent 4 prompt from MCP server
```
### Option 3: Validation Only
```
Use MCP server to validate form 21p-0516 for all check types
```
---
## 🏗️ Architecture
```
┌─────────────────────────────────────┐
│ Claude Desktop / Claude Code │
└──────────────┬──────────────────────┘
│ MCP Protocol
┌──────────────▼──────────────────────┐
│ VA Form Generation MCP Server │
│ (External - ~/va-form-generation) │
│ │
│ Tools: │
│ ✓ audit_form │
│ ✓ get_agent_prompt │
│ ✓ validate_form │
│ ✓ get_fix_reference │
│ ✓ generate_orchestration_prompt │
│ │
│ Resources: │
│ ✓ Master checklist │
│ ✓ Agent prompts (1-4) │
│ ✓ Fix references │
└──────────────┬──────────────────────┘
│ File System Access
┌──────────────▼──────────────────────┐
│ vets-website Workspace │
│ /Users/aponce/Workspaces/... │
└─────────────────────────────────────┘
```
---
## 📦 What Gets Fixed
### Component Patterns (6 fixes)
✅ yesNoUI simplified to `yesNoUI('question')`
✅ Import paths corrected
✅ radioSchema called with enum values
✅ Duplicate imports removed
### Architecture (5 fixes)
✅ IntroductionPage rewritten
✅ ConfirmationPage uses ConfirmationView
✅ submit-transformer follows 21P-601
✅ prefill-transformer accesses profile
✅ form.js has fullNamePath
### Content (3 fixes)
✅ Plain language (you/we, contractions)
✅ Person-centered titles
✅ PDF-accurate labels
### Syntax (2 fixes)
✅ Apostrophe errors
✅ Schema validation
**Total: 16+ automated fixes**
---
## 🔧 Development
### Run in Dev Mode
```bash
npm run dev
```
### Add New Tools
Edit `index.js` and add to the `tools` array in `ListToolsRequestSchema` handler.
### Add New Resources
Edit `index.js` and add to the `resources` array in `ListResourcesRequestSchema` handler.
### Update Templates
Edit files in `templates/` directory.
---
## 📖 Examples
### Example 1: Quick Audit
```
I'm working on form 21p-0516. Use the MCP server to audit it and tell me what needs to be fixed.
Workspace: /Users/aponce/Workspaces/vets-website
```
### Example 2: Get Specific Fix
```
Use the MCP server to show me how to fix the radioSchema pattern
```
### Example 3: Full Automation
```
Use the MCP server to:
1. Audit form 21p-527ez
2. Generate the orchestration prompt
3. Launch all 4 agents in the correct order
Workspace: /Users/aponce/Workspaces/vets-website
```
### Example 4: Validation
```
Use the MCP server to validate form 21p-0516 for schema errors and apostrophe syntax
Form path: /Users/aponce/Workspaces/vets-website/src/applications/simple-forms/21p-0516
```
---
## 🎓 Learn More
- **Master Checklist:** `templates/master-checklist.md`
- **Agent Prompts:** `templates/agent-{1-4}-prompt.md`
- **MCP Protocol:** https://modelcontextprotocol.io/
---
## 🚢 Sharing with Team
### Method 1: Git Repository
```bash
cd ~/va-form-generation-mcp
git init
git add .
git commit -m "Initial MCP server"
git remote add origin YOUR_REPO_URL
git push -u origin main
```
Team members clone and configure:
```bash
git clone YOUR_REPO_URL ~/va-form-generation-mcp
cd ~/va-form-generation-mcp
npm install
# Add to claude_desktop_config.json
```
### Method 2: npm Package (Private Registry)
```bash
npm publish --registry YOUR_PRIVATE_REGISTRY
```
Team members install:
```bash
npm install -g va-form-generation-mcp --registry YOUR_PRIVATE_REGISTRY
```
---
## ❓ FAQ
### Q: Does this modify the vets-website repo?
**A:** No! The MCP server lives completely outside the VA repo. It only provides tools and prompts - Claude does the actual modifications.
### Q: Can multiple people use this?
**A:** Yes! Each team member installs it separately and points it to their own vets-website workspace.
### Q: What if the VA changes their patterns?
**A:** Update the templates in this repo. Everyone pulls the updates. No VA PR needed!
### Q: Can I customize it?
**A:** Absolutely! Edit the templates or add new tools specific to your needs.
### Q: Does it work with Claude Code in VS Code?
**A:** Yes! As long as Claude Code supports MCP servers, it will work.
---
## 📝 License
MIT
---
**Questions?** Open an issue or ask Claude: "Explain the va-form-generation MCP server"
