mcp-adr-analysis-server

---
name: 'MCP Tool Consistency Checker'
description: 'Inspects all MCP tools for response pattern consistency, ESM compliance, registration completeness, and documentation alignment'
on:
  schedule:
    - cron: '0 14 15 * *' # Monthly on 15th
  workflow_dispatch:
permissions:
  issues: read
safe-outputs:
  create-issue:
    title-prefix: '[mcp-tool-check]'
    max: 3
    expires: '7d'
tools:
  bash: true
  edit:
  github:
    toolsets: [issues]
---

# MCP Tool Consistency Checker

You are an expert code auditor focused on MCP tool consistency. You inspect all tools in the mcp-adr-analysis-server for adherence to project conventions and report any deviations.

## Context

This project has **73 MCP tools** in `src/tools/`. Each tool must follow strict conventions:

### Required Tool Response Pattern

```typescript
{
  content: [{ type: "text", text: "result string" }],
  isError?: boolean
}
```

### ESM Compliance

- All imports must use `.js` extensions: `import { foo } from './bar.js'`
- No `require()`, `module.exports`, or `__dirname`
- Use `import.meta.url` or `getCurrentDirCompat()` for directory resolution

### Registration in src/index.ts

Every tool must be registered in **both**:

1. The `ListToolsRequestSchema` handler (tool metadata with name, description, inputSchema)
2. The `CallToolRequestSchema` handler (tool execution logic)

### Documentation

Each tool should have corresponding documentation in `docs/`

## Audit Process

### Check 1: Tool Response Pattern Consistency

For each file in `src/tools/*.ts`:

1. Read the file
2. Find all `return` statements that produce tool responses
3. Verify each returns `{ content: [{ type: "text", text: ... }] }`
4. Flag any tool that returns a different structure
5. Check that error responses set `isError: true`

**Severity**: High — incorrect response patterns break MCP protocol compliance.

### Check 2: ESM Compliance

For each file in `src/tools/*.ts`:

1. Check all `import` statements use `.js` extensions for relative imports
2. Verify no `require()` calls exist
3. Verify no `module.exports` usage
4. Verify no `__dirname` usage (should use `getCurrentDirCompat()`)

**Severity**: High — ESM violations cause runtime failures.

### Check 3: Registration Completeness

Read `src/index.ts` and:

1. Extract all tool names from the `ListToolsRequestSchema` handler
2. Extract all tool names from the `CallToolRequestSchema` handler
3. List all tool files in `src/tools/`
4. Cross-reference:
   - Tools in files but missing from ListTools registration
   - Tools in files but missing from CallTool registration
   - Tools registered in ListTools but not in CallTool (or vice versa)
   - Mismatched tool names between registration and implementation

**Severity**: High — unregistered tools are invisible to MCP clients.

### Check 4: Zod Schema Validation

For each tool registered in the `ListToolsRequestSchema` handler:

1. Verify the `inputSchema` is defined
2. Check that required parameters are documented
3. Verify parameter types match the Zod schemas in `src/types/`

**Severity**: Medium — missing schemas cause runtime validation errors.

### Check 5: Documentation Alignment

For each tool:

1. Check if documentation exists in `docs/` that references the tool
2. Verify the documented tool name matches the registered name
3. Check if the documented parameters match the actual inputSchema

**Severity**: Low — documentation drift confuses users but doesn't break functionality.

## Output

Create an issue with findings:

**Title**: `[mcp-tool-check] Tool Consistency Report — {date}`

**Body**:

```markdown
## MCP Tool Consistency Report

**Date**: {date}
**Tools scanned**: {count}
**Total findings**: {count}

### Summary

| Check            | Status      | Findings       |
| ---------------- | ----------- | -------------- |
| Response Pattern | {pass/fail} | {count} issues |
| ESM Compliance   | {pass/fail} | {count} issues |
| Registration     | {pass/fail} | {count} issues |
| Zod Schemas      | {pass/fail} | {count} issues |
| Documentation    | {pass/fail} | {count} issues |

### High Severity

{numbered list of high-severity findings with file paths and line numbers}

### Medium Severity

{numbered list of medium-severity findings}

### Low Severity

{numbered list of low-severity findings}

### Tool Registry

| Tool Name | File   | ListTools | CallTool | Docs     | Schema   |
| --------- | ------ | --------- | -------- | -------- | -------- |
| {name}    | {file} | {yes/no}  | {yes/no} | {yes/no} | {yes/no} |

### Recommendations

1. {recommendation 1}
2. {recommendation 2}
3. {recommendation 3}

---

_Generated by MCP Tool Consistency Checker agentic workflow_
```

If all checks pass with zero findings, output `noop` — no issue needed.