# codefactor-mcp

![Node.js](https://img.shields.io/badge/Node.js-20+-339933.svg?logo=node.js&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-Server-5C5CFF.svg)
![CodeFactor](https://img.shields.io/badge/CodeFactor-Issues-0AA1A5.svg)

**English** | [简体中文](README_CN.md)

**codefactor-mcp** is a local MCP server for reading [CodeFactor](https://www.codefactor.io/) 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

## 🚀 Quick Start

### Prerequisites

- Node.js 20+
- A CodeFactor repository issues URL, for example:

```text
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:

```powershell
cd codefactor_mcp
npm install
npm run build
```

The built MCP entry point is:

```text
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:

```text
%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:

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

Then provide the repository URL in your request:

```text
请使用 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:

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

### Option 2: Configure A Default Repository

Use this when most tasks target the same repository:

```toml
[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:

```toml
[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:

```text
<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:

```powershell
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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

| Argument | Description |
|------|------|
| `url` | CodeFactor repository or issues URL; falls back to `CODEFACTOR_REPOSITORY_URL` |
| `cookie` | Optional Cookie header; falls back to `CODEFACTOR_COOKIE` |
| `allPages` | Whether to fetch multiple issue pages |
| `maxPages` | Maximum pages to fetch when `allPages` is true |
| `category` | Filter by category, such as `Complexity` |
| `filePathIncludes` | Filter by file path text |
| `maxIssues` | Limit the number of returned issues |
| `includeHidden` | Include hidden issues; defaults to false |

### `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:

```text
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

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

### Use A Specific Repository

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

### Focus On Complexity

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

### Focus On One Module

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

### Parse Pasted HTML

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

## 🛠️ Development And Verification

```powershell
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`