AI导哈

SonarCloud项目管理工具

一个用于与SonarCloud项目、问题、质量门和安全热点交互的MCP服务器实现。

  • by lukleh
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 lukleh/mcp-sonarcloud

使用说明

MCP SonarCloud Server

A Model Context Protocol (MCP) server implementation for SonarCloud, providing tools to interact with SonarCloud projects, issues, quality gates, and security hotspots.

Default layout:

  • Config: ~/.config/lukleh/mcp-sonarcloud/config.toml
  • Credentials: injected via the MCP client or shell environment
  • State: ~/.local/state/lukleh/mcp-sonarcloud/
  • Cache: ~/.cache/lukleh/mcp-sonarcloud/

Features

This MCP server provides 15 comprehensive tools with detailed parameter documentation and examples:

Project Management (3 tools)

  • search_my_sonarqube_projects: List all SonarCloud projects in your organization with pagination
  • show_component: Get detailed metadata for a specific project or component
  • component_tree: Traverse the file/directory structure of a project

Issues (4 tools)

  • search_sonar_issues_in_projects: Search for issues with filtering by pull request, severity (INFO, LOW, MEDIUM, HIGH, BLOCKER), and more
  • list_issue_authors: Discover SCM authors who contributed to issues
  • get_issue_changelog: Retrieve the change history of an issue
  • list_issue_tags: List available tags used on issues

Quality Gates (5 tools)

  • get_project_quality_gate_status: Get the quality gate status (OK, ERROR, WARN, NONE) for a project, branch, or pull request
  • list_quality_gates: List all quality gates in your organization
  • show_quality_gate: Get detailed conditions for a specific quality gate
  • search_quality_gates: Find projects associated with a quality gate
  • get_quality_gate_by_project: Get the quality gate assigned to a project

Security Hotspots (3 tools)

  • search_hotspots: Search for security hotspots in a project with file, branch, or PR filters
  • show_hotspot: Get detailed information about a specific hotspot
  • change_hotspot_status: Change the status of a hotspot (TO_REVIEW or REVIEWED with resolution: FIXED, SAFE, ACKNOWLEDGED)

All tools include comprehensive parameter descriptions, valid value documentation, and usage examples for optimal AI agent integration.

Prerequisites

  • Python 3.11 or higher
  • uv package manager
  • A SonarCloud account with an API token
  • Claude Code or Codex AI client

Quick Start

1. Get Your SonarCloud Token

  1. Log in to SonarCloud
  2. Click on your avatar → My Account → Security
  3. Under "Generate Tokens", enter a name (e.g., "MCP Server")
  4. Click Generate
  5. Copy and save the token - you won't be able to see it again!

2. Find Your Organization Key

  1. Go to your organization on SonarCloud
  2. Look at the URL: https://sonarcloud.io/organizations/YOUR-ORG-KEY
  3. The YOUR-ORG-KEY part is your organization key

3. Install the Server

# Run the published package without cloning the repository
uvx mcp-sonarcloud@latest --write-sample-config

# Or install it once and reuse the command directly
uv tool install mcp-sonarcloud@latest
mcp-sonarcloud --write-sample-config

4. Create the Config File

The command above writes a starter config to ~/.config/lukleh/mcp-sonarcloud/config.toml. You can confirm the resolved runtime locations at any time:

uvx mcp-sonarcloud@latest --print-paths

Edit ~/.config/lukleh/mcp-sonarcloud/config.toml:

base_url = "https://sonarcloud.io"
organization = "your-org-key"
timeout_sec = 30

5. Set the Token Environment Variable

Set SONARCLOUD_TOKEN in the environment used to launch the server. For local shell testing, you can export it directly:

export SONARCLOUD_TOKEN=your-token-here

6. Configure Your AI Client

Claude Code:

claude mcp add sonarcloud \
  --scope {local, user, or project} \
  -e SONARCLOUD_TOKEN=your-token-here \
  -- uvx mcp-sonarcloud@latest

Codex:

codex mcp add sonarcloud \
  --env SONARCLOUD_TOKEN=your-token-here \
  -- uvx mcp-sonarcloud@latest

Important: Replace your-token-here with your real SonarCloud token.

7. Restart and Test

  1. Restart your AI client
  2. Try asking: "Can you list my SonarCloud projects?"

Configuration

Files

  • config.toml
    • base_url (optional): SonarCloud or SonarQube base URL
    • organization (optional): SonarCloud organization key
    • timeout_sec (optional): HTTP timeout in seconds

Environment Overrides

Environment variables are the source of secrets and also override file values when present:

  • SONARCLOUD_TOKEN
  • SONARCLOUD_ORGANIZATION
  • SONARCLOUD_URL
  • SONARCLOUD_TIMEOUT_SEC

Command Line Testing

You can test the server directly:

# Show the resolved runtime paths
uvx mcp-sonarcloud@latest --print-paths

# Write or refresh the default config file
uvx mcp-sonarcloud@latest --write-sample-config
uvx mcp-sonarcloud@latest --write-sample-config --overwrite

# Export the token for local testing
export SONARCLOUD_TOKEN=your-token-here

# Run the server with the default home-directory config
uvx mcp-sonarcloud@latest

# Or point at a different config root
uvx mcp-sonarcloud@latest --config-dir /path/to/config-dir

Local Development

If you want to work on the repository itself:

git clone https://github.com/lukleh/mcp-sonarcloud.git
cd mcp-sonarcloud
uv sync --extra dev
uv run pytest -q
uv run mcp-sonarcloud --print-paths

Usage Examples

Natural Language Queries

Once configured, you can ask your AI client:

  1. List projects: "Show me all my SonarCloud projects"
  2. Check quality gate: "What's the quality gate status for project X on PR 123?"
  3. Search hotspots: "Find all security hotspots in project X"
  4. Get hotspot details: "Show me details for hotspot AY1234567890"
  5. Update hotspot: "Mark hotspot AY1234567890 as reviewed and safe"
  6. Search issues: "Find all blocker issues in project X's pull request 123"

Tool Examples (Python)

List Projects

# Get first page of projects
search_my_sonarqube_projects(page="1")

Search Issues in Pull Request

# Search for issues in a specific pull request
search_sonar_issues_in_projects(
    projects=["my-project"],
    pullRequestId="123",
    ps=100
)

Check Quality Gate Status

# Get quality gate status for a pull request
get_project_quality_gate_status(
    projectKey="my-project",
    pullRequest="123"
)

Search Security Hotspots

# Search hotspots in a project
search_hotspots(
    projectKey="my-project",
    pullRequest="123"
)

# Search hotspots in a specific file
search_hotspots(
    projectKey="my-project",
    files="src/main/java/com/example/MyClass.java",
    branch="main"
)

Get Hotspot Details

# Get detailed information about a hotspot
show_hotspot(hotspot="AX1234567890")

Change Hotspot Status

# Mark a hotspot as reviewed and safe
change_hotspot_status(
    hotspot="AX1234567890",
    status="REVIEWED",
    resolution="SAFE"
)

# Mark a hotspot for review
change_hotspot_status(
    hotspot="AX1234567890",
    status="TO_REVIEW"
)

Valid status values:

  • TO_REVIEW: Mark for review
  • REVIEWED: Mark as reviewed (requires resolution)

Valid resolution values (when status=REVIEWED):

  • FIXED: The vulnerability has been fixed
  • SAFE: The code is safe and not a vulnerability
  • ACKNOWLEDGED: The risk is acknowledged but accepted

Troubleshooting

Common Issues

"Config file already exists"

  • --write-sample-config will not replace an existing file unless you add --overwrite
  • Use uvx mcp-sonarcloud@latest --print-paths to confirm which config path is active

"SONARCLOUD_TOKEN environment variable is required"

  • Double-check your token is correctly set in the environment variables
  • Verify there are no extra spaces or quotes around the token

"401 Unauthorized"

  • Your token might be invalid or expired
  • Generate a new token from SonarCloud and update your configuration

MCP server not available

  • Verify the server was added: claude mcp list or codex mcp list
  • Run uvx mcp-sonarcloud@latest --print-paths in your shell to confirm the package starts cleanly
  • Try removing and re-adding the server
  • Check your AI client logs for errors

API Endpoints Used

This server uses the following SonarCloud API endpoints:

Components / Projects

  • GET /api/components/search - List projects
  • GET /api/components/show - Show component metadata
  • GET /api/components/tree - Traverse component hierarchy

Issues

  • GET /api/issues/search - Search issues
  • GET /api/issues/authors - List issue authors
  • GET /api/issues/changelog - Get issue change history
  • GET /api/issues/tags - List issue tags

Quality Gates

  • GET /api/qualitygates/project_status - Get quality gate status
  • GET /api/qualitygates/list - List quality gates
  • GET /api/qualitygates/show - Show quality gate details
  • GET /api/qualitygates/search - Search projects by quality gate
  • GET /api/qualitygates/get_by_project - Get quality gate for project

Security Hotspots

  • GET /api/hotspots/search - Search security hotspots
  • GET /api/hotspots/show - Show hotspot details
  • POST /api/hotspots/change_status - Change hotspot status

For complete API documentation, see SONARCLOUD_API_SUPPORT.md.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Releasing

Maintainer release instructions live in RELEASING.md.

License

MIT License - see LICENSE file for details

相关 MCP