{"_id":"@autodevops/verifier-mcp","name":"@autodevops/verifier-mcp","dist-tags":{"latest":"0.3.0"},"versions":{"0.3.0":{"name":"@autodevops/verifier-mcp","version":"0.3.0","description":"Model Context Protocol (MCP) server for verifier agents and signed AutoDevOps agent-activity event emission","type":"module","main":"dist/index.js","bin":{"verifier-mcp":"dist/index.js","verifier-mcp-walkthrough":"dist/walkthrough-client.js"},"scripts":{"build":"npm --workspace @autodevops/verifier-portal-client run build && tsc -p tsconfig.json && chmod +x dist/index.js dist/walkthrough-client.js","clean":"rm -rf dist","dev":"tsc -w","prepublishOnly":"npm run clean && npm run build"},"keywords":["mcp","model-context-protocol","verifier","claude","ai","code-analysis"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/autodevopsai/autodevops.git","directory":"packages/verifier-mcp"},"bugs":{"url":"https://github.com/autodevopsai/autodevops/issues"},"homepage":"https://autodevops.ai","dependencies":{"@autodevops/verifier-portal-client":"^0.1.0","@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.23.8"},"devDependencies":{"@types/node":"^20.14.2","typescript":"^5.4.5"},"engines":{"node":">=18"},"publishConfig":{"access":"public"},"_id":"@autodevops/verifier-mcp@0.3.0","gitHead":"c606f3266c1d0de9daa4c031eb27a393dd2e2bd5","types":"./dist/index.d.ts","_nodeVersion":"23.11.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-jMzlVkUcOl9O6Ku3g93yGGZ5FfB8aac2rfHEoamledE04LRVJQDPShjdK1yxf3kfiwIg5qDS7anY0tpQYFUQCQ==","shasum":"987b13f71adc3dcee658a500050fc54af3993b20","tarball":"https://registry.npmjs.org/@autodevops/verifier-mcp/-/verifier-mcp-0.3.0.tgz","fileCount":10,"unpackedSize":158439,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFko5IxMGJG4+3lCzVZz3ZBaxpzIHNuP9lmtZE+GujjwAiEAk4xJkaWfyptZr+ob/UWSA0j0zT51DoijyFkGRhpjOQA="}]},"_npmUser":{"name":"brij-singh","email":"opensource@sociallabs.com"},"directories":{},"maintainers":[{"name":"bsociallabs","email":"brij@sociallabs.com"},{"name":"brij-singh","email":"opensource@sociallabs.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/verifier-mcp_0.3.0_1784959185187_0.3054344216587781"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-25T05:59:45.026Z","0.3.0":"2026-07-25T05:59:45.322Z","modified":"2026-07-25T05:59:45.573Z"},"maintainers":[{"name":"bsociallabs","email":"brij@sociallabs.com"},{"name":"brij-singh","email":"opensource@sociallabs.com"}],"description":"Model Context Protocol (MCP) server for verifier agents and signed AutoDevOps agent-activity event emission","homepage":"https://autodevops.ai","keywords":["mcp","model-context-protocol","verifier","claude","ai","code-analysis"],"repository":{"type":"git","url":"git+https://github.com/autodevopsai/autodevops.git","directory":"packages/verifier-mcp"},"bugs":{"url":"https://github.com/autodevopsai/autodevops/issues"},"license":"MIT","readme":"# Verifier MCP Server\n\nModel Context Protocol (MCP) server that exposes verifier CLI agents and signed AutoDevOps agent-activity event emission for Claude Code and other MCP clients.\n\n## Overview\n\nThis MCP server bridges verifier CLI workflows with MCP-aware coding agents. It exposes verifier agents (security-scan, lint, test-coverage, etc.) and lets third-party agents emit signed `agent_activity.v1` events into the AutoDevOps verification portal.\n\n## Features\n\n- **21 MCP Tools**: CLI parity plus signed agent-activity and intent emission\n- **5 MCP Resources**: Agent docs, config schema, quickstart guide, health status\n- **4 MCP Prompts**: Pre-built workflows for security audit, code review, pre-commit checks\n- **Agent Activity Emission**: Start sessions, emit tool/model/approval events, and finish sessions through the portal ingest endpoint\n- **Structured Errors**: Helpful error messages with recovery suggestions\n- **Agent Execution**: Run any verifier agent on your codebase\n- **Discovery**: List available agents dynamically\n- **Monitoring**: Track token usage and costs\n- **Health Checks**: Validate environment and configuration\n- **Setup**: Initialize verifier from Claude\n- **Demo Mode**: Test without API keys\n\n## Installation\n\n### Global Installation (Recommended)\n\n```bash\n# Install the core CLI\nnpm install -g @autodevops/verifier\n\n# Install the optional MCP server if you want Claude Code / MCP integration\nnpm install -g @autodevops/verifier-mcp\n```\n\n### Local Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/autodevopsai/autodevops.git\ncd autodevops\n\n# Install dependencies\nnpm install\n\n# Build the MCP server\nnpm --workspace packages/verifier-mcp run build\n\n# Link for local testing\ncd packages/verifier-mcp && npm link\n```\n\n## Claude Code Integration\n\n### Method 1: Claude Desktop App\n\nAdd to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"verifier\": {\n      \"command\": \"verifier-mcp\"\n    }\n  }\n}\n```\n\n### Method 2: Claude Code CLI\n\nAdd to your project's `.claude/mcp-config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"verifier\": {\n      \"command\": \"verifier-mcp\",\n      \"env\": {\n        \"PATH\": \"/usr/local/bin:/usr/bin:/bin\"\n      }\n    }\n  }\n}\n```\n\n### Method 3: Development Mode (Local Build)\n\nIf working from the monorepo:\n\n```json\n{\n  \"mcpServers\": {\n    \"verifier\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/autodevops/packages/verifier-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n## Available MCP Tools\n\n### Agent Activity Emission\n\nThese tools emit `agent_activity.v1` events to `/api/verification-portal/ingest` using the same HMAC headers as the verifier runtime.\n\nConfigure credentials through environment variables:\n\n```bash\nexport AUTODEVOPS_PORTAL_INGEST_ENDPOINT=\"https://your-portal.example.com/api/verification-portal/ingest\"\nexport AUTODEVOPS_PORTAL_INGEST_SECRET=\"your-hmac-secret\"\nexport AUTODEVOPS_TEAM_ID=\"00000000-0000-4000-8000-000000000000\"\n```\n\nOptional:\n\n```bash\nexport AUTODEVOPS_PORTAL_TIMEOUT_MS=3000\nexport AUTODEVOPS_MCP_SOURCE_NAME=\"claude-code\"\nexport AUTODEVOPS_MCP_SOURCE_VERSION=\"1.0.0\"\n```\n\n#### `autodevops_start_agent_session`\n\nRegisters a session by emitting `session.started`.\n\n```json\n{\n  \"event_id\": \"mcp-walkthrough:claude-session-123:session-started\",\n  \"session_id\": \"claude-session-123\",\n  \"agent\": { \"id\": \"claude-code\", \"name\": \"Claude Code\", \"provider\": \"anthropic\" },\n  \"developer\": {\n    \"id\": \"dev-123\",\n    \"email_hash\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n  },\n  \"repository\": { \"name\": \"payments-service\", \"branch\": \"main\" }\n}\n```\n\n#### `autodevops_emit_agent_activity`\n\nEmits a generic session/tool/model/approval/policy/result event. Use `dry_run: true` to validate and inspect the signed payload shape without posting.\n\n```json\n{\n  \"event_type\": \"tool.finished\",\n  \"event_family\": \"tool\",\n  \"session\": { \"id\": \"claude-session-123\" },\n  \"agent\": { \"id\": \"claude-code\", \"name\": \"Claude Code\" },\n  \"tool\": {\n    \"name\": \"shell\",\n    \"input_summary\": \"npm test\",\n    \"input_hash\": \"sha256:...\"\n  },\n  \"outcome\": { \"status\": \"succeeded\", \"summary\": \"Tests passed\" }\n}\n```\n\n#### `autodevops_finish_agent_session`\n\nFinishes a session by emitting `session.finished`.\n\n```json\n{\n  \"session_id\": \"claude-session-123\",\n  \"status\": \"succeeded\",\n  \"summary\": \"Claude Code run completed\"\n}\n```\n\n## Live Walkthrough Helper\n\nUse `verifier-mcp-walkthrough` when collecting connector proof. It runs a real MCP stdio client against `verifier-mcp`, verifies the required event-emission tools, calls the existing MCP tools, posts through the configured portal ingest endpoint, and writes the scrubbed `agent_activity.v1` transcript for conformance and connector proof receipts.\n\n```bash\nverifier-mcp-walkthrough --check-env\nverifier-mcp-walkthrough --check-env \\\n  --output-assertions artifacts/connector-proof/mcp/mcp-output-assertions.json\n\nverifier-mcp-walkthrough \\\n  --session-id mcp-session-123 \\\n  --repository-name payments-service \\\n  --repository-commit abc1234def5678 \\\n  --events-output artifacts/connector-proof/mcp/events.jsonl \\\n  --summary-output artifacts/connector-proof/mcp/mcp-walkthrough-output.json \\\n  --output-assertions artifacts/connector-proof/mcp/mcp-output-assertions.json\n```\n\nThe helper requires `AUTODEVOPS_PORTAL_INGEST_ENDPOINT`, `AUTODEVOPS_PORTAL_INGEST_SECRET`, and `AUTODEVOPS_TEAM_ID` for live proof. It does not create a separate event path; it exercises the same MCP server tools a third-party MCP client uses.\nThe output-assertions file is merge-written so the setup and live capture commands can contribute command-id-keyed assertions for `autodevops-connector-proof-walkthrough-run --output-assertions`.\nCustomer-cloud connector proof plans for `agent_source: \"mcp\"` are validated to call this helper for setup and live session capture. Substituting a generic command, handwritten transcript, or hook-pack install command fails the plan verifier before the run report or receipt can support an MCP live-proof claim.\n\n### 1. `verifier_run`\n\nRun a verifier agent to analyze code.\n\n**Input:**\n```json\n{\n  \"agent\": \"security-scan\",\n  \"files\": [\"src/app.ts\", \"src/utils.ts\"],\n  \"demo\": false\n}\n```\n\n**Output:**\n```json\n{\n  \"success\": true,\n  \"agent\": \"security-scan\",\n  \"result\": {\n    \"agent_id\": \"security-scan\",\n    \"status\": \"success\",\n    \"severity\": \"warning\",\n    \"score\": 6,\n    \"data\": {\n      \"risk_score\": 6,\n      \"vulnerabilities\": [\n        {\n          \"type\": \"SQL Injection\",\n          \"severity\": \"high\",\n          \"description\": \"Unsanitized user input in SQL query\",\n          \"location\": \"src/db.ts:42\",\n          \"recommendation\": \"Use parameterized queries\"\n        }\n      ],\n      \"summary\": \"Found 1 high-severity vulnerability\"\n    },\n    \"tokens_used\": 2150,\n    \"cost\": 0.086,\n    \"timestamp\": \"2025-10-21T10:30:00.000Z\"\n  }\n}\n```\n\n**Available Agents:**\n- `security-scan` - Scan for security vulnerabilities\n- `lint` - Check code quality and style\n- `test-coverage` - Analyze test coverage\n- `code-complexity` - Measure code complexity\n- `cleanup-guard` - Detect debug code and TODOs\n- `todo-auditor` - Audit TODO comments\n- `claude-agent` - Custom Claude-powered analysis\n\n### 2. `verifier_list`\n\nList all available agents.\n\n**Input:**\n```json\n{}\n```\n\n**Output:**\n```\n📋 Available agents (7):\n  • cleanup-guard — Cleanup Guard — Detects leftover debug code, console.log, TODOs\n  • claude-agent — Claude Agent — Custom agent powered by Claude\n  • code-complexity — Code Complexity Analyzer — Measures cyclomatic complexity\n  • lint — Lint Agent — Checks code quality and style\n  • security-scan — Security Scanner — Scans code for security vulnerabilities\n  • test-coverage — Test Coverage Agent — Analyzes test coverage\n  • todo-auditor — TODO Auditor — Audits TODO comments\n```\n\n### 3. `verifier_token_usage`\n\nShow token usage statistics and costs.\n\n**Input:**\n```json\n{\n  \"period\": \"daily\",\n  \"format\": \"json\"\n}\n```\n\n**Output:**\n```json\n{\n  \"period\": \"daily\",\n  \"total_tokens\": 15420,\n  \"total_cost\": 0.62,\n  \"by_agent\": {\n    \"security-scan\": { \"tokens\": 8200, \"cost\": 0.33, \"runs\": 4 },\n    \"lint\": { \"tokens\": 5120, \"cost\": 0.20, \"runs\": 3 },\n    \"test-coverage\": { \"tokens\": 2100, \"cost\": 0.09, \"runs\": 2 }\n  },\n  \"budget_remaining\": {\n    \"daily_tokens\": 84580,\n    \"monthly_cost\": 99.38\n  }\n}\n```\n\n### 4. `verifier_doctor`\n\nVerify environment and configuration.\n\n**Input:**\n```json\n{}\n```\n\n**Output:**\n```json\n{\n  \"success\": true,\n  \"initialized\": true,\n  \"output\": \"✅ Verifier initialized\\n✅ Configuration valid\\n✅ API keys configured\\n✅ Git repository detected\",\n  \"errors\": \"\"\n}\n```\n\n### 5. `verifier_init`\n\nInitialize verifier in the current repository.\n\n**Input:**\n```json\n{\n  \"force\": false\n}\n```\n\n**Output:**\n```json\n{\n  \"success\": true,\n  \"message\": \"Verifier initialized successfully\",\n  \"output\": \"Created .verifier/config.yaml\\nCreated .verifier/.env\\nAdded .verifier/.env to .gitignore\"\n}\n```\n\n### 6. `verifier_quickstart`\n\nOne-command setup and first agent run.\n\n**Input:**\n```json\n{}\n```\n\n**Output:**\n```json\n{\n  \"success\": true,\n  \"output\": \"🚀 Initializing verifier...\\n✅ Configuration created\\n🎬 Running demo security scan...\\n✅ Found 2 potential issues\"\n}\n```\n\n### 7. `verifier_config`\n\nManage verifier configuration.\n\n**Input:**\n```json\n{\n  \"action\": \"show\"\n}\n```\n\n### 8. `verifier_judge`\n\nEvaluate prompt/response pairs using LLM-as-a-judge.\n\n**Input:**\n```json\n{\n  \"action\": \"evaluate\",\n  \"prompt\": \"Write a function to sort an array\",\n  \"response\": \"function sort(arr) { return arr.sort(); }\",\n  \"rubric\": \"Evaluate for correctness and edge cases\"\n}\n```\n\n### 9. `verifier_hooks`\n\nList and manage configured hooks for LLM providers.\n\n**Input:**\n```json\n{\n  \"provider\": \"claude\"\n}\n```\n\n### 10. `verifier_plugins`\n\nList installed plugins and their status.\n\n**Input:**\n```json\n{\n  \"action\": \"list\"\n}\n```\n\n### 11. `verifier_sandbox`\n\nExecute commands in a sandboxed environment.\n\n**Input:**\n```json\n{\n  \"action\": \"exec\",\n  \"command\": \"npm test\"\n}\n```\n\n### 12. `verifier_worktree`\n\nManage git worktrees for parallel development.\n\n**Input:**\n```json\n{\n  \"action\": \"list\"\n}\n```\n\n### 13. `verifier_cache`\n\nManage verifier cache (clear, list, info, prune, stats).\n\n**Input:**\n```json\n{\n  \"action\": \"stats\"\n}\n```\n\n### 14. `verifier_workflow`\n\nManage and run verifier workflows.\n\n**Input:**\n```json\n{\n  \"action\": \"list\"\n}\n```\n\n### 15. `verifier_exec`\n\nGeneric CLI execution for advanced commands.\n\n**Input:**\n```json\n{\n  \"args\": [\"--help\"]\n}\n```\n\n## MCP Resources\n\nThe server exposes read-only resources for documentation and status:\n\n| Resource URI | Description |\n|--------------|-------------|\n| `verifier://agents/list` | List of all verification agents |\n| `verifier://config/schema` | Configuration schema with defaults |\n| `verifier://docs/quickstart` | Quickstart guide |\n| `verifier://docs/agents` | Agent documentation |\n| `verifier://status/health` | Current health status |\n\n## MCP Prompts\n\nPre-built workflow templates for common tasks:\n\n| Prompt Name | Description |\n|-------------|-------------|\n| `security-audit` | Comprehensive security audit workflow |\n| `code-review` | Full code quality review |\n| `pre-commit-check` | Pre-commit verification checks |\n| `test-coverage-analysis` | Test coverage analysis and recommendations |\n\n## Usage Examples\n\n### Example 1: Security Scan from Claude\n\n**You:** \"Run a security scan on my authentication code\"\n\n**Claude:** [Uses `verifier_run` tool]\n```json\n{\n  \"agent\": \"security-scan\",\n  \"files\": [\"src/auth.ts\", \"src/middleware/auth.ts\"]\n}\n```\n\n**Result:** Claude receives detailed vulnerability report and suggests fixes.\n\n### Example 2: Check Code Quality\n\n**You:** \"What agents are available?\"\n\n**Claude:** [Uses `verifier_list` tool]\n\nShows all available agents with descriptions.\n\n**You:** \"Run the lint agent\"\n\n**Claude:** [Uses `verifier_run` tool]\n```json\n{\n  \"agent\": \"lint\"\n}\n```\n\n### Example 3: Monitor Costs\n\n**You:** \"How much have I spent on verifier this week?\"\n\n**Claude:** [Uses `verifier_token_usage` tool]\n```json\n{\n  \"period\": \"weekly\",\n  \"format\": \"json\"\n}\n```\n\nShows token usage and costs by agent.\n\n### Example 4: Initial Setup\n\n**You:** \"Set up verifier in my project\"\n\n**Claude:** [Uses `verifier_init` tool, then `verifier_doctor` to confirm]\n\nInitializes configuration and validates setup.\n\n## Configuration\n\nThe MCP server uses the verifier CLI, which requires configuration in `.verifier/`:\n\n### `.verifier/config.yaml`\n\n```yaml\nmodels:\n  primary: gpt-4o-mini\n  fallback: claude-3-5-sonnet-20241022\n\nbudgets:\n  daily_tokens: 100000\n  per_commit_tokens: 5000\n  monthly_cost: 100\n\nthresholds:\n  drift_score: 30\n  security_risk: 5\n  coverage_delta: -5\n\nhooks:\n  generic:\n    pre-commit: [security-scan, lint]\n    pre-push: [test-coverage]\n```\n\n### `.verifier/.env`\n\n```bash\nOPENAI_API_KEY=sk-...\nANTHROPIC_API_KEY=sk-ant-...\nGOOGLE_API_KEY=...\n```\n\n## Troubleshooting\n\n### \"Verifier CLI is not installed\"\n\n**Solution:** Install verifier globally:\n```bash\nnpm install -g @autodevops/verifier\n```\n\n### \"Failed to list agents\"\n\n**Solution:** Ensure verifier is initialized:\n```bash\nverifier init\n```\n\n### MCP server not responding\n\n**Solution:** Check logs in Claude Desktop:\n- macOS: `~/Library/Logs/Claude/mcp*.log`\n- Check that `verifier-mcp` is in your PATH\n\n### Tool execution errors\n\n**Solution:** Run verifier doctor:\n```bash\nverifier doctor\n```\n\nCommon issues:\n- Missing API keys\n- Invalid configuration\n- No git repository\n- Insufficient permissions\n\n## Architecture\n\n```\n┌─────────────────┐\n│   Claude Code   │\n│   (MCP Client)  │\n└────────┬────────┘\n         │ MCP Protocol (stdio)\n         ▼\n┌─────────────────┐\n│  Verifier MCP   │\n│     Server      │\n└────────┬────────┘\n         │ execSync\n         ▼\n┌─────────────────┐\n│  Verifier CLI   │\n│   (verifier)    │\n└────────┬────────┘\n         │\n         ▼\n┌─────────────────┐\n│     Agents      │\n│  (TypeScript)   │\n└─────────────────┘\n```\n\n**Flow:**\n1. Claude Code sends MCP tool request\n2. MCP server validates input with Zod schemas\n3. Server executes `verifier` command via `execSync`\n4. Verifier CLI loads and runs the agent\n5. Agent analyzes code using LLM\n6. Result flows back through MCP to Claude\n\n## Development\n\n### Building\n\n```bash\nnpm run build\n```\n\n### Testing Locally\n\n```bash\n# Build the server\nnpm run build\n\n# Test with echo (simulates MCP client)\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | node dist/index.js\n\n# Test tool execution\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"verifier_list\",\"arguments\":{}}}' | node dist/index.js\n\n# Test the live proof helper surface without posting events\nAUTODEVOPS_PORTAL_INGEST_ENDPOINT=https://portal.example.invalid/api/verification-portal/ingest \\\nAUTODEVOPS_PORTAL_INGEST_SECRET=redacted \\\nAUTODEVOPS_TEAM_ID=00000000-0000-4000-8000-000000000000 \\\nnode dist/walkthrough-client.js --check-env --output-assertions /tmp/mcp-output-assertions.json\n```\n\n### Adding New Tools\n\n1. Define Zod schema in `src/index.ts`\n2. Add tool to `ListToolsRequestSchema` handler\n3. Add case to `CallToolRequestSchema` handler\n4. Build and test\n\nExample:\n```typescript\nconst MyToolSchema = z.object({\n  param: z.string().describe(\"Description\"),\n});\n\n// In ListToolsRequestSchema handler:\n{\n  name: \"verifier_my_tool\",\n  description: \"What this tool does\",\n  inputSchema: {\n    type: \"object\",\n    properties: {\n      param: { type: \"string\", description: \"Description\" }\n    }\n  }\n}\n\n// In CallToolRequestSchema handler:\ncase \"verifier_my_tool\": {\n  const parsed = MyToolSchema.parse(args);\n  // Execute verifier command\n}\n```\n\n## Security\n\n- **No credential storage**: MCP server reads from `.verifier/.env`\n- **Sandboxed execution**: Uses `execSync` with buffer limits\n- **Input validation**: All inputs validated with Zod schemas\n- **Error isolation**: Errors don't expose sensitive data\n\n## Contributing\n\nContributions welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new tools\n4. Submit a pull request\n\nSee [CONTRIBUTING.md](../../CONTRIBUTING.md) for details.\n\n## License\n\nMIT License - see [LICENSE](../../LICENSE)\n\n## Links\n\n- **Documentation**: https://autodevops.ai/docs/verifier\n- **GitHub**: https://github.com/autodevopsai/autodevops\n- **npm**: https://npmjs.com/package/@autodevops/verifier-mcp\n- **MCP Protocol**: https://modelcontextprotocol.io\n- **Claude Code**: https://claude.ai/code\n\n## Support\n\n- **Issues**: https://github.com/autodevopsai/autodevops/issues\n- **Discord**: https://discord.gg/autodevops (coming soon)\n- **Email**: support@autodevops.ai\n","readmeFilename":"README.md","_rev":"1-b7fb34242808b4c0faf40438609bce97"}