# PMAT MCP Tools Catalog

**Protocol Version**: MCP v2024-11-05
**Last Updated**: October 19, 2025
**Total Tools**: 19

## Table of Contents

1. [Overview](#overview)
2. [Documentation Quality Tools](#documentation-quality-tools)
3. [Code Quality Tools](#code-quality-tools)
4. [Agent-Based Analysis Tools](#agent-based-analysis-tools)
5. [Deep WASM Analysis Tools](#deep-wasm-analysis-tools)
6. [Semantic Search Tools](#semantic-search-tools)
7. [Testing Tools](#testing-tools)

---

## Overview

PMAT (Polyglot Multi-Language Analysis Toolkit) exposes its code analysis capabilities via MCP (Model Context Protocol), enabling AI agents to:

- Validate documentation accuracy against actual codebase
- Analyze code quality and technical debt
- Perform deep WebAssembly analysis
- Search code semantically
- Run mutation tests
- Orchestrate complex analysis workflows

**Protocol Compliance**: All tools follow MCP v2024-11-05 specification.

---

## Documentation Quality Tools

### 1. `validate_documentation`

**Category**: Documentation Quality (Sprint 40a)
**Source**: `server/src/mcp_integration/hallucination_detection_tools.rs:21`

Validates documentation files against the actual codebase to detect hallucinations, contradictions, and broken references.

**Scientific Foundation**:
- Semantic Entropy (Farquhar et al., Nature 2024)
- MIND framework (IJCAI 2025)
- Unified Detection Framework (Complex & Intelligent Systems 2025)

**Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "documentation_path": {
      "type": "string",
      "description": "Path to documentation file (README.md, CLAUDE.md, etc.)"
    },
    "deep_context_path": {
      "type": "string",
      "description": "Path to deep context file (generated via `pmat context`)"
    },
    "similarity_threshold": {
      "type": "number",
      "default": 0.7,
      "description": "Similarity threshold for claim validation (0.0-1.0)"
    },
    "fail_on_error": {
      "type": "boolean",
      "default": false,
      "description": "Whether to fail on unverified/contradicted claims"
    }
  },
  "required": ["documentation_path", "deep_context_path"]
}
```

**Output Format**:
```json
{
  "status": "completed",
  "summary": {
    "total_claims": 42,
    "verified": 38,
    "unverified": 2,
    "contradictions": 1,
    "not_found": 1,
    "pass": true
  },
  "results": [
    {
      "claim": "PMAT can analyze TypeScript complexity",
      "status": "Verified",
      "confidence": 0.94,
      "evidence": ["server/src/cli/language_analyzer.rs:150"]
    }
  ]
}
```

**Example Usage**:
```javascript
const result = await mcpClient.callTool("validate_documentation", {
  documentation_path: "README.md",
  deep_context_path: "deep_context.md",
  similarity_threshold: 0.7,
  fail_on_error: true
});
```

**Use Cases**:
- Pre-commit hooks to verify documentation accuracy
- CI/CD validation gates
- Documentation quality audits
- Preventing documentation drift

---

### 2. `check_claim`

**Category**: Documentation Quality (Sprint 40a)
**Source**: `server/src/mcp_integration/hallucination_detection_tools.rs:197`

Validates a single claim against the codebase to determine if it's accurate, unverified, or a contradiction.

**Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "claim": {
      "type": "string",
      "description": "The claim to validate"
    },
    "deep_context_path": {
      "type": "string",
      "description": "Path to deep context file"
    },
    "similarity_threshold": {
      "type": "number",
      "default": 0.7
    }
  },
  "required": ["claim", "deep_context_path"]
}
```

**Output Format**:
```json
{
  "status": "Verified",
  "confidence": 0.94,
  "evidence": ["server/src/cli/language_analyzer.rs:150"],
  "claim": "PMAT can analyze TypeScript complexity"
}
```

**Example Usage**:
```javascript
const result = await mcpClient.callTool("check_claim", {
  claim: "PMAT can analyze TypeScript complexity",
  deep_context_path: "deep_context.md",
  similarity_threshold: 0.7
});
```

**Use Cases**:
- Interactive documentation writing
- Real-time claim verification
- Documentation review workflows

---

## Code Quality Tools

### 3. `analyze_technical_debt`

**Category**: Code Quality (Sprint 40c)
**Source**: `server/src/mcp_integration/tdg_tools.rs:14`

Analyzes technical debt gradient (TDG) for files or projects, providing comprehensive quality metrics and grades (A+ to F).

**Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Path to file or directory to analyze"
    },
    "analysis_type": {
      "type": "string",
      "enum": ["file", "project", "auto"],
      "default": "auto",
      "description": "Type of analysis (auto-detects by default)"
    },
    "include_penalties": {
      "type": "boolean",
      "default": true,
      "description": "Include detailed penalty breakdown"
    }
  },
  "required": ["path"]
}
```

**Output Format (File Analysis)**:
```json
{
  "status": "completed",
  "analysis_type": "file",
  "path": "src/main.rs",
  "score": {
    "total": 78.5,
    "grade": "B",
    "confidence": 0.92,
    "language": "Rust",
    "structural_complexity": 45.2,
    "semantic_complexity": 32.1,
    "duplication_ratio": 0.05,
    "coupling_score": 0.15,
    "doc_coverage": 0.85,
    "consistency_score": 0.91,
    "entropy_score": 0.12
  },
  "penalties": [
    {
      "source_metric": "CyclomaticComplexity",
      "amount": 5.2,
      "issue": "Function has high cyclomatic complexity (15)"
    }
  ]
}
```

**Output Format (Project Analysis)**:
```json
{
  "status": "completed",
  "analysis_type": "project",
  "path": "src/",
  "total_files": 142,
  "average_score": 82.3,
  "average_grade": "B+",
  "file_scores": [
    {
      "file": "src/main.rs",
      "total": 78.5,
      "grade": "B"
    }
  ]
}
```

**Example Usage**:
```javascript
// Analyze a single file
const fileResult = await mcpClient.callTool("analyze_technical_debt", {
  path: "src/main.rs",
  include_penalties: true
});

// Analyze an entire project
const projectResult = await mcpClient.callTool("analyze_technical_debt", {
  path: "src/",
  analysis_type: "project"
});
```

**Use Cases**:
- Pre-commit quality checks
- Code review automation
- Technical debt tracking
- Quality trend analysis

---

### 4. `get_quality_recommendations`

**Category**: Code Quality (Sprint 40c)
**Source**: `server/src/mcp_integration/tdg_tools.rs:165`

Generates actionable, contextual refactoring recommendations based on quality analysis.

**Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Path to file to analyze"
    },
    "max_recommendations": {
      "type": "number",
      "default": 10,
      "description": "Maximum number of recommendations to return"
    },
    "min_severity": {
      "type": "string",
      "enum": ["low", "medium", "high", "critical"],
      "default": "low",
      "description": "Minimum severity level to include"
    }
  },
  "required": ["path"]
}
```

**Output Format**:
```json
{
  "status": "completed",
  "path": "src/main.rs",
  "recommendations": [
    {
      "severity": "high",
      "category": "CyclomaticComplexity",
      "issue": "Function has high cyclomatic complexity (15)",
      "suggestion": "Consider breaking down complex functions into smaller, single-responsibility functions. Extract conditional logic into separate helper functions. Use early returns to reduce nesting depth.",
      "impact": 8.5
    },
    {
      "severity": "medium",
      "category": "NestingDepth",
      "issue": "Deep nesting detected (level 6)",
      "suggestion": "Reduce nesting depth by using early returns, guard clauses, or extracting nested blocks into separate functions. Consider using pattern matching or polymorphism to flatten control flow.",
      "impact": 4.2
    }
  ],
  "total_score": 78.5,
  "grade": "B"
}
```

**Example Usage**:
```javascript
const recommendations = await mcpClient.callTool("get_quality_recommendations", {
  path: "src/complex_module.rs",
  max_recommendations: 5,
  min_severity: "medium"
});

// Focus on critical issues only
const criticalIssues = await mcpClient.callTool("get_quality_recommendations", {
  path: "src/main.rs",
  min_severity: "critical"
});
```

**Contextual Suggestions by Category**:
- **Cyclomatic Complexity**: Break down functions, extract logic
- **Nesting Depth**: Use early returns, guard clauses
- **Duplication**: Extract common logic into shared functions
- **Coupling**: Introduce interfaces, reduce dependencies
- **Documentation**: Add docstrings, explain complex logic
- **Consistency**: Follow naming conventions, formatting rules

**Use Cases**:
- AI-assisted code review
- Automated refactoring suggestions
- Developer education
- Quality improvement roadmaps

---

## Agent-Based Analysis Tools

### 5. `analyze`

**Category**: Agent-Based Analysis
**Source**: `server/src/mcp_integration/tools.rs:13`

Invokes the analyzer agent to analyze code for quality metrics and issues.

**Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Source code to analyze"
    },
    "language": {
      "type": "string",
      "description": "Programming language (rust, python, typescript, etc.)"
    },
    "metrics": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Metrics to calculate (complexity, duplication, etc.)"
    },
    "priority": {
      "type": "string",
      "enum": ["low", "normal", "high", "critical"],
      "default": "normal"
    }
  },
  "required": ["code", "language"]
}
```

**Example Usage**:
```javascript
const analysis = await mcpClient.callTool("analyze", {
  code: "fn main() { println!(\"Hello\"); }",
  language: "rust",
  metrics: ["complexity", "style"],
  priority: "normal"
});
```

---

### 6. `transform`

**Category**: Agent-Based Analysis
**Source**: `server/src/mcp_integration/tools.rs:135`

Invokes the transformer agent to transform code (refactor, optimize, modernize).

**Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Source code to transform"
    },
    "transformation": {
      "type": "string",
      "description": "Type of transformation (refactor, optimize, modernize)"
    },
    "language": {
      "type": "string"
    }
  },
  "required": ["code", "transformation", "language"]
}
```

---

### 7. `validate`

**Category**: Agent-Based Analysis
**Source**: `server/src/mcp_integration/tools.rs:270`

Invokes the validator agent to validate code against rules and standards.

---

### 8. `orchestrate`

**Category**: Agent-Based Analysis
**Source**: `server/src/mcp_integration/tools.rs:425`

Orchestrates complex multi-agent workflows (analyze → transform → validate).

---

## Deep WASM Analysis Tools

### 9. `deep_wasm_analyze`

**Category**: WebAssembly Analysis
**Source**: `server/src/mcp_integration/deep_wasm_tools.rs:16`

Performs deep WebAssembly bytecode analysis.

---

### 10. `deep_wasm_query_mapping`

**Category**: WebAssembly Analysis
**Source**: `server/src/mcp_integration/deep_wasm_tools.rs:170`

Queries WASM-to-source mappings.

---

### 11. `deep_wasm_trace_execution`

**Category**: WebAssembly Analysis
**Source**: `server/src/mcp_integration/deep_wasm_tools.rs:375`

Traces WebAssembly execution paths.

---

### 12. `deep_wasm_compare_optimizations`

**Category**: WebAssembly Analysis
**Source**: `server/src/mcp_integration/deep_wasm_tools.rs:424`

Compares WebAssembly optimization strategies.

---

### 13. `deep_wasm_detect_issues`

**Category**: WebAssembly Analysis
**Source**: `server/src/mcp_integration/deep_wasm_tools.rs:474`

Detects common WebAssembly issues and anti-patterns.

---

## Semantic Search Tools

### 14. `semantic_search`

**Category**: Semantic Search
**Source**: `server/src/mcp_integration/tools.rs:679`

Searches code semantically using embeddings (requires OpenAI API key).

---

### 15. `find_similar_code`

**Category**: Semantic Search
**Source**: `server/src/mcp_integration/tools.rs:729`

Finds similar code patterns across the codebase.

---

### 16. `cluster_code`

**Category**: Semantic Search
**Source**: `server/src/mcp_integration/tools.rs:777`

Clusters code by semantic similarity.

---

### 17. `analyze_topics`

**Category**: Semantic Search
**Source**: `server/src/mcp_integration/tools.rs:825`

Analyzes code topics and themes.

---

## Testing Tools

### 18. `mutation_test`

**Category**: Testing
**Source**: `server/src/mcp_integration/mutation_tools.rs:11`

Runs mutation testing to verify test suite quality.

---

### 19. `quality_gate`

**Category**: Testing
**Source**: `server/src/mcp_integration/tools.rs:569`

Runs comprehensive quality gate checks.

---

## Error Handling

All tools follow consistent error patterns:

**Error Codes**:
- `-32700`: Parse error
- `-32600`: Invalid request
- `-32601`: Method not found
- `-32602`: Invalid parameters
- `-32603`: Internal error

**Error Response Format**:
```json
{
  "code": -32602,
  "message": "Path does not exist: /invalid/path",
  "data": {
    "path": "/invalid/path",
    "suggestion": "Please provide a valid file or directory path"
  }
}
```

**Best Practices**:
- Always check `status` field in responses
- Handle errors gracefully with fallback logic
- Use `data.suggestion` for actionable error recovery

---

## Tool Discovery

To discover available tools at runtime:

```javascript
const tools = await mcpClient.listTools();
console.log(tools.tools.map(t => t.name));
```

---

## Next Steps

- [Integration Guide](INTEGRATION.md) - How to connect to the MCP server
- [JVM Language Tools](JVM-TOOLS.md) - Java and Scala language analysis tools (New in Sprint 51)
- [Examples](../../examples/) - Complete usage examples
- [Architecture](../architecture/) - System architecture documentation

---

**Maintained by**: PMAT Development Team
**Last Updated**: Sprint 51 (October 24, 2025)
