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 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:

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

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"