codefactor-mcp

English | 简体中文

codefactor-mcp is a local MCP server for reading CodeFactor repository issue pages.

✨ Features

• Parse CodeFactor issues: extracts issue data from the embedded model in CodeFactor pages

• Normalize issue details: outputs file paths, categories, severity, metrics, line ranges, preview code, and recommendations

• Generate summaries: converts CodeFactor issues into Markdown for quick reading

Related MCP server: code-health-mcp

🚀 Quick Start

Prerequisites

• Node.js 20+

• A CodeFactor repository issues URL, for example:

https://www.codefactor.io/repository/github/5656565566/aylink.extra/issues

If the CodeFactor page requires a logged-in session, you also need a browser Cookie header.

Install And Build

Clone the project:

git clone https://github.com/5656565566/codefactor_mcp.git

Then run:

cd codefactor_mcp
npm install
npm run build

The built MCP entry point is:

codefactor_mcp\dist\index.js

In the examples below, replace <CODEFACTOR_MCP_DIR> with the actual install directory of your local codefactor-mcp project.

⚙️ Codex Configuration

Codex uses:

%USERPROFILE%\.codex\config.toml

After changing this file, restart Codex or open a new session.

Option 1: Let AI Choose The Repository

Use this when you want the AI to pass the CodeFactor repository URL for each task:

[mcp_servers.codefactor]
command = 'node'
args = ['<CODEFACTOR_MCP_DIR>\dist\index.js']
startup_timeout_sec = 30

Then provide the repository URL in your request:

请使用 codefactor MCP 检查这个仓库，并在修改代码时遵守它的代码建议：
https://www.codefactor.io/repository/github/5656565566/aylink.extra/issues

You can also ask the AI to inspect the current Git remote and derive the CodeFactor URL:

请根据当前仓库 remote 推导 CodeFactor issues 地址，然后调用 codefactor MCP 获取建议。

Option 2: Configure A Default Repository

Use this when most tasks target the same repository:

[mcp_servers.codefactor]
command = 'node'
args = ['<CODEFACTOR_MCP_DIR>\dist\index.js']
startup_timeout_sec = 30

[mcp_servers.codefactor.env]
CODEFACTOR_REPOSITORY_URL = 'https://www.codefactor.io/repository/github/5656565566/aylink.extra/issues'

Tool behavior:

• If url is not provided, the tool uses CODEFACTOR_REPOSITORY_URL

• If url is provided, the tool uses that URL for the current call

Option 3: Configure Login Cookie

Use this only when CodeFactor requires a logged-in browser session:

[mcp_servers.codefactor]
command = 'node'
args = ['<CODEFACTOR_MCP_DIR>\dist\index.js']
startup_timeout_sec = 30

[mcp_servers.codefactor.env]
CODEFACTOR_REPOSITORY_URL = 'https://www.codefactor.io/repository/github/5656565566/aylink.extra/issues'
CODEFACTOR_COOKIE = 'paste browser Cookie header here'

Notes:

• Do not commit CODEFACTOR_COOKIE

• Do not share cookies with untrusted AI clients or third-party services

• Cookies may expire and need to be refreshed

🔌 Other Platform Configuration

Different MCP clients use different config file locations and root fields. All examples below use this built entry point:

<CODEFACTOR_MCP_DIR>\dist\index.js

If you want the AI to choose the repository, remove env from the examples and pass url when calling the tool.

Claude Code

Install globally for the current user:

claude mcp add --scope user codefactor -- node <CODEFACTOR_MCP_DIR>\dist\index.js

For project-scoped shared configuration, create .mcp.json in the project root:

{
  "mcpServers": {
    "codefactor": {
      "type": "stdio",
      "command": "node",
      "args": [
        "<CODEFACTOR_MCP_DIR>\\dist\\index.js"
      ],
      "env": {
        "CODEFACTOR_REPOSITORY_URL": "https://www.codefactor.io/repository/github/5656565566/aylink.extra/issues"
      }
    }
  }
}

After starting Claude Code, use /mcp to check the connection.

Claude Desktop

Common config file locations:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Example:

{
  "mcpServers": {
    "codefactor": {
      "command": "node",
      "args": [
        "<CODEFACTOR_MCP_DIR>\\dist\\index.js"
      ],
      "env": {
        "CODEFACTOR_REPOSITORY_URL": "https://www.codefactor.io/repository/github/5656565566/aylink.extra/issues"
      }
    }
  }
}

Save the file, then fully quit and reopen Claude Desktop.

Cursor

Common configuration options:

• Global: ~/.cursor/mcp.json

• Project-level: .cursor/mcp.json in the project root

• You can also add it from Cursor's MCP / Tools settings page

Example:

{
  "mcpServers": {
    "codefactor": {
      "command": "node",
      "args": [
        "<CODEFACTOR_MCP_DIR>\\dist\\index.js"
      ],
      "env": {
        "CODEFACTOR_REPOSITORY_URL": "https://www.codefactor.io/repository/github/5656565566/aylink.extra/issues"
      }
    }
  }
}

After adding it, refresh the MCP / Tools page or restart the Cursor window.

VS Code / GitHub Copilot

VS Code uses servers as the root field, not mcpServers.

Common config locations:

• Workspace: .vscode/mcp.json

• User-level: run MCP: Open User Configuration from the Command Palette

Example:

{
  "servers": {
    "codefactor": {
      "command": "node",
      "args": [
        "<CODEFACTOR_MCP_DIR>\\dist\\index.js"
      ],
      "env": {
        "CODEFACTOR_REPOSITORY_URL": "https://www.codefactor.io/repository/github/5656565566/aylink.extra/issues"
      }
    }
  }
}

To share the configuration with a team, prefer the workspace .vscode/mcp.json file.

Windsurf / Cascade

Common configuration options:

• Add from Settings > Tools > Windsurf Settings > Add Server

• Or click View Raw Config and edit mcp_config.json

Common config file locations:

• Windows: %APPDATA%\Codeium\Windsurf\mcp_config.json

• macOS / Linux: ~/.codeium/windsurf/mcp_config.json

Example:

{
  "mcpServers": {
    "codefactor": {
      "command": "node",
      "args": [
        "<CODEFACTOR_MCP_DIR>\\dist\\index.js"
      ],
      "env": {
        "CODEFACTOR_REPOSITORY_URL": "https://www.codefactor.io/repository/github/5656565566/aylink.extra/issues"
      }
    }
  }
}

After adding it, refresh the MCP plugin list or restart Windsurf.

Generic JSON MCP Clients

If a client uses the standard mcpServers layout, use:

{
  "mcpServers": {
    "codefactor": {
      "type": "stdio",
      "command": "node",
      "args": [
        "<CODEFACTOR_MCP_DIR>\\dist\\index.js"
      ],
      "env": {
        "CODEFACTOR_REPOSITORY_URL": "https://www.codefactor.io/repository/github/5656565566/aylink.extra/issues"
      }
    }
  }
}

If the client does not support the type field, remove "type": "stdio".

🧰 MCP Tools

fetch_codefactor_issues

Fetches issues from https://www.codefactor.io and returns normalized JSON.

Common arguments:

summarize_codefactor_issues

Returns a compact Markdown summary. This is useful before code review or refactoring work.

build_codefactor_prompt

Builds an AI-facing prompt from CodeFactor issues. This is the recommended tool before asking an AI agent to edit code.

The generated prompt asks the AI to:

• Prefer CodeFactor issues within the current scope

• For complexity issues, extract functions, name intermediate concepts, and decompose conditionals

• For duplication issues, extract shared logic

• For maintainability issues, remove truly unused code or duplicate selectors

• Preserve the project's existing comment style

• Run relevant validation and report coverage

parse_codefactor_html

Parses a raw HTML string. Use this when you already have the CodeFactor page response from browser DevTools or curl.

🧭 MCP Prompt

The server exposes one prompt:

follow-codefactor-advice

It asks the AI to read CodeFactor issues before editing code and keep the fix scoped and maintainable.

📌 Usage Examples

Use The Default Repository

先调用 codefactor MCP 生成代码建议提示，然后按提示修复当前问题。

Use A Specific Repository

请对这个仓库调用 codefactor MCP，并在修改代码时遵守建议：
https://www.codefactor.io/repository/github/5656565566/aylink.extra/issues

Focus On Complexity

{
  "url": "https://www.codefactor.io/repository/github/5656565566/aylink.extra/issues",
  "category": "Complexity",
  "allPages": true,
  "maxPages": 4,
  "maxIssues": 20
}

Focus On One Module

{
  "filePathIncludes": "AYLink.Web/src/features/screencast",
  "allPages": true,
  "maxPages": 4,
  "maxIssues": 20
}

Parse Pasted HTML

{
  "html": "<!DOCTYPE html>..."
}

🛠️ Development And Verification

npm run build
npm test
npm run typecheck

You can also run MCP discovery with a client. The server should expose these tools:

• parse_codefactor_html

• fetch_codefactor_issues

• build_codefactor_prompt

• summarize_codefactor_issues

And this prompt:

• follow-codefactor-advice

📄 Notes

• Repository URLs may omit /issues; the server appends it automatically

• CodeFactor issue pages may be paginated; use allPages: true when full context is needed

• Public repositories usually do not need cookies

• Private or logged-in pages may need CODEFACTOR_COOKIE