Diagnostics Module

The Diagnostics module provides language-agnostic error and warning detection across multiple programming languages. It automatically identifies the appropriate diagnostic tool for your project and returns structured, actionable error information.

Overview

Instead of manually running different linters and compilers for each language, the Diagnostics module:

  • Auto-detects project type by analyzing file structure
  • Runs appropriate tools (cargo, tsc, eslint, pylint, etc.)
  • Parses output into structured JSON format
  • Provides detailed locations (file, line, column) for every issue
  • Categorizes severity (error, warning, info)

Supported Languages & Tools

Rust

  • Tool: cargo check
  • Detection: Presence of Cargo.toml
  • Features:
    • Compile-time error detection
    • Borrow checker violations
    • Type mismatches
    • Unused variables and imports
    • Macro expansion errors

TypeScript/JavaScript

  • Tools: tsc (TypeScript), eslint (ESLint)
  • Detection: tsconfig.json or .eslintrc.*
  • Features:
    • Type checking errors
    • Linting violations
    • Code style issues
    • Potential bugs
    • Best practice violations

Python

  • Tools: pylint, flake8, mypy
  • Detection: .py files, requirements.txt, setup.py
  • Features:
    • Syntax errors
    • Style violations (PEP 8)
    • Code quality issues
    • Type hint errors (with mypy)
    • Potential bugs

C/C++

  • Tools: gcc, clang
  • Detection: .c, .cpp, .h files, CMakeLists.txt, Makefile
  • Features:
    • Compile-time errors
    • Warnings
    • Memory issues (with sanitizers)
    • Undefined behavior detection

Available Tool

diagnostics_get

Get errors and warnings for files or entire projects.

Parameters:

  • path (string, required) - Path to file or project directory
  • severity (array, optional) - Filter by severity: ["error", "warning", "info"]
  • tool (string, optional) - Force specific tool: "cargo", "tsc", "eslint", "pylint", etc.
  • fix (boolean, optional) - Attempt automatic fixes where possible (default: false)

Example - Auto-detect:

{
  "name": "diagnostics_get",
  "arguments": {
    "path": "./src"
  }
}

Example - Specific Tool:

{
  "name": "diagnostics_get",
  "arguments": {
    "path": "./src",
    "tool": "eslint",
    "severity": ["error", "warning"]
  }
}

Example - With Auto-fix:

{
  "name": "diagnostics_get",
  "arguments": {
    "path": "./src/main.ts",
    "tool": "eslint",
    "fix": true
  }
}

Output Format

The tool returns a structured response with all diagnostics:

{
  "project_type": "typescript",
  "tool_used": "tsc",
  "total_errors": 3,
  "total_warnings": 5,
  "diagnostics": [
    {
      "file": "src/main.ts",
      "line": 42,
      "column": 15,
      "severity": "error",
      "code": "TS2322",
      "message": "Type 'string' is not assignable to type 'number'",
      "suggestion": "Change variable type to string or convert the value"
    },
    {
      "file": "src/utils.ts",
      "line": 10,
      "column": 5,
      "severity": "warning",
      "code": "TS6133",
      "message": "Unused variable 'unused'",
      "suggestion": "Remove unused variable or prefix with underscore"
    }
  ],
  "execution_time_ms": 1234
}

Language-Specific Examples

Rust Projects

Common Errors Detected:

{
  "file": "src/main.rs",
  "severity": "error",
  "code": "E0308",
  "message": "mismatched types",
  "details": "expected `i32`, found `&str`"
}

Borrow Checker:

{
  "file": "src/lib.rs",
  "severity": "error",
  "code": "E0502",
  "message": "cannot borrow `x` as mutable because it is also borrowed as immutable"
}

TypeScript Projects

Type Errors:

{
  "file": "src/app.ts",
  "severity": "error",
  "code": "TS2339",
  "message": "Property 'foo' does not exist on type 'MyType'"
}

Strict Null Checks:

{
  "file": "src/utils.ts",
  "severity": "error",
  "code": "TS2531",
  "message": "Object is possibly 'null'"
}

Python Projects

Syntax Errors:

{
  "file": "main.py",
  "severity": "error",
  "code": "E0001",
  "message": "invalid syntax"
}

Style Violations:

{
  "file": "utils.py",
  "severity": "warning",
  "code": "C0103",
  "message": "Variable name doesn't conform to snake_case naming style"
}

Use Cases

Pre-commit Checks

Run diagnostics before committing code:

// 1. Get current git status
{"name": "git_status", "arguments": {"path": "."}}

// 2. Run diagnostics on changed files
{"name": "diagnostics_get", "arguments": {"path": "./src"}}

// 3. Block commit if errors found
// 4. Auto-fix warnings if possible
{"name": "diagnostics_get", "arguments": {"path": "./src", "fix": true}}

Continuous Integration

Validate code in CI pipelines:

{
  "name": "diagnostics_get",
  "arguments": {
    "path": ".",
    "severity": ["error"]
  }
}
// Exit with error if any diagnostics found

IDE Integration

Provide real-time feedback:

// Watch for file changes
{"name": "fs_watch", "arguments": {"path": "./src", "events": ["modify"]}}

// Run diagnostics on change
{"name": "diagnostics_get", "arguments": {"path": "./src/modified_file.ts"}}

Code Review

Automated code quality checks:

// 1. Get diff of changes
{"name": "git_diff", "arguments": {"path": ".", "staged": false}}

// 2. Run diagnostics on entire project
{"name": "diagnostics_get", "arguments": {"path": "."}}

// 3. Compare with baseline to find new issues

Auto-detection Logic

The module uses the following priority for auto-detection:

  1. Check for config files:

    • Cargo.toml → Rust
    • tsconfig.json → TypeScript
    • .eslintrc.* → JavaScript/TypeScript
    • pyproject.toml, setup.py → Python
    • CMakeLists.txt, Makefile → C/C++

  2. Analyze file extensions:

    • .rs → Rust
    • .ts, .tsx → TypeScript
    • .js, .jsx → JavaScript
    • .py → Python
    • .c, .cpp, .h → C/C++

  3. Check for tool availability:

    • Verify the diagnostic tool is installed
    • Fall back to alternative tools if primary unavailable

Error Handling

Tool Not Found

{
  "error": {
    "code": -32001,
    "message": "Diagnostic tool not found: tsc",
    "suggestion": "Install TypeScript: npm install -g typescript"
  }
}

Project Type Unknown

{
  "error": {
    "code": -32002,
    "message": "Could not detect project type for path: ./unknown",
    "suggestion": "Specify tool explicitly using 'tool' parameter"
  }
}

Compilation Failed

{
  "error": {
    "code": -32003,
    "message": "Diagnostic tool crashed",
    "stdout": "...",
    "stderr": "..."
  }
}

Performance Optimization

Incremental Checks

For large projects, run diagnostics on specific files:

// Instead of checking entire project
{"name": "diagnostics_get", "arguments": {"path": "."}}

// Check only modified files
{"name": "diagnostics_get", "arguments": {"path": "./src/modified_file.ts"}}

Caching

The module caches diagnostic results for unchanged files:

  • Cache invalidation: File modification time
  • Cache location: In-memory (process lifetime)
  • Cache size: Configurable via environment variable

Parallel Execution

For multi-language projects, diagnostics run in parallel:

// Runs TypeScript and Python checks concurrently
{"name": "diagnostics_get", "arguments": {"path": "./mixed_project"}}

Configuration

Configure diagnostic tools via environment variables:

# Rust
export RUSTFLAGS="-D warnings"  # Treat warnings as errors

# TypeScript
export TSC_FLAGS="--strict"     # Enable strict mode

# Python
export PYLINT_RCFILE=".pylintrc"  # Custom config file

# ESLint
export ESLINT_CONFIG=".eslintrc.json"

Integration Examples

With Git Module

Check diagnostics before committing:

// 1. Stage files
{"name": "git_status", "arguments": {"path": "."}}

// 2. Run diagnostics
{"name": "diagnostics_get", "arguments": {"path": ".", "severity": ["error"]}}

// 3. If no errors, proceed with commit
{"name": "git_commit", "arguments": {"message": "feat: add feature"}}

With Filesystem Module

Auto-fix and save:

// 1. Run diagnostics with fix
{"name": "diagnostics_get", "arguments": {"path": "./src", "fix": true}}

// 2. Create snapshot before applying fixes
{"name": "fs_snapshot", "arguments": {"path": "./src"}}

// 3. Apply fixes (done automatically by diagnostic tool)

With Silent Module

Run in CI pipeline:

{
  "name": "silent_script",
  "arguments": {
    "script": "#!/bin/bash\nresult=$(poly-mcp diagnostics_get ./src)\nif [ $? -ne 0 ]; then exit 1; fi",
    "timeout": 300
  }
}

Best Practices

1. Run Diagnostics Frequently

Integrate into your development workflow:

  • Pre-commit hooks
  • File save hooks
  • CI/CD pipelines

2. Address Errors Before Warnings

Focus on errors first, then tackle warnings for code quality.

3. Use Auto-fix Carefully

  • Review auto-fix changes before committing
  • Create snapshots before applying fixes
  • Test after auto-fix to ensure correctness

4. Configure Tools Appropriately

  • Use .eslintrc, pylintrc, etc. for project-specific rules
  • Enable strict mode for better error detection
  • Customize severity levels for your team

5. Monitor Performance

  • Use incremental checks for large projects
  • Cache results when possible
  • Run expensive checks only in CI

Troubleshooting

False Positives

Configure tool-specific ignore rules:

ESLint:

/* eslint-disable no-unused-vars */

Pylint:

# pylint: disable=unused-variable

Rust:

#[allow(dead_code)]

Tool Version Mismatches

Ensure consistent tool versions across environments:

# Lock versions
npm install --save-dev typescript@5.0.0
pip install pylint==2.17.0

Path Resolution Issues

Use absolute paths to avoid resolution problems:

{
  "name": "diagnostics_get",
  "arguments": {
    "path": "/absolute/path/to/project"
  }
}