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
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:
{
"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:
{
"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:
{
"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:
- Copy the templates from
~/va-form-generation-mcp/templates/ - Paste them directly into ChatGPT conversations
- 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 patternsradioSchema- How to fix radioSchema callsapostrophes- How to fix apostrophe syntaxtransformers- How to fix submit/prefill transformersfullNamePath- 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
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
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:
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)
npm publish --registry YOUR_PRIVATE_REGISTRY
Team members install:
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"