# 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"