Skip to main content
Glama
sapientpants

DeepSource MCP Server

by sapientpants

DeepSource MCP Server

Main DeepSource DeepSource DeepSource npm version npm downloads License

A Model Context Protocol (MCP) server that integrates with DeepSource to provide AI assistants with access to code quality metrics, issues, and analysis results.

Table of Contents

Related MCP server: CodeAlive MCP

Overview

The DeepSource MCP Server enables AI assistants like Claude to interact with DeepSource's code quality analysis capabilities through the Model Context Protocol. This integration allows AI assistants to:

  • Retrieve code metrics and analysis results

  • Access and filter issues by analyzer, path, or tags

  • Check quality status and set thresholds

  • Analyze project quality over time

  • Access security compliance reports (OWASP, SANS, MISRA-C)

  • Monitor dependency vulnerabilities

  • Manage quality gates and thresholds

Quick Start

1. Get Your DeepSource API Key

  1. Log in to your DeepSource account

  2. Navigate to SettingsAPI Access

  3. Click Generate New Token

  4. Copy your API key and keep it secure

2. Install in Claude Desktop

  1. Open Claude Desktop

  2. Go to SettingsDeveloperEdit Config

  3. Add this configuration to the mcpServers section:

{
  "mcpServers": {
    "deepsource": {
      "command": "npx",
      "args": ["-y", "deepsource-mcp-server@latest"],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key"
      }
    }
  }
}
  1. Restart Claude Desktop

3. Test Your Connection

Ask Claude: "What DeepSource projects do I have access to?"

If configured correctly, Claude will list your available projects.

Installation

The simplest way to use the DeepSource MCP Server:

{
  "mcpServers": {
    "deepsource": {
      "command": "npx",
      "args": ["-y", "deepsource-mcp-server@latest"],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key",
        "LOG_FILE": "/tmp/deepsource-mcp.log",
        "LOG_LEVEL": "INFO",
        "RETRY_MAX_ATTEMPTS": "3",
        "RETRY_BASE_DELAY_MS": "1000",
        "RETRY_MAX_DELAY_MS": "30000",
        "RETRY_BUDGET_PER_MINUTE": "10",
        "CIRCUIT_BREAKER_THRESHOLD": "5",
        "CIRCUIT_BREAKER_TIMEOUT_MS": "30000"
      }
    }
  }
}

Docker

For containerized environments:

{
  "mcpServers": {
    "deepsource": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DEEPSOURCE_API_KEY",
        "-e",
        "LOG_FILE=/tmp/deepsource-mcp.log",
        "-v",
        "/tmp:/tmp",
        "sapientpants/deepsource-mcp-server"
      ],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key"
      }
    }
  }
}

Local Development

For development or customization:

{
  "mcpServers": {
    "deepsource": {
      "command": "node",
      "args": ["/path/to/deepsource-mcp-server/dist/index.js"],
      "env": {
        "DEEPSOURCE_API_KEY": "your-deepsource-api-key",
        "LOG_FILE": "/tmp/deepsource-mcp.log",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Configuration

Environment Variables

Variable

Required

Default

Description

DEEPSOURCE_API_KEY

Yes

-

Your DeepSource API key for authentication

LOG_FILE

No

-

Path to log file. If not set, no logs are written

LOG_LEVEL

No

DEBUG

Minimum log level: DEBUG, INFO, WARN, ERROR

RETRY_MAX_ATTEMPTS

No

3

Maximum number of retry attempts for failed requests

RETRY_BASE_DELAY_MS

No

1000

Base delay in milliseconds for exponential backoff

RETRY_MAX_DELAY_MS

No

30000

Maximum delay in milliseconds between retries

RETRY_BUDGET_PER_MINUTE

No

10

Maximum retries allowed per minute across all operations

CIRCUIT_BREAKER_THRESHOLD

No

5

Number of failures before circuit breaker opens

CIRCUIT_BREAKER_TIMEOUT_MS

No

30000

Time in milliseconds before circuit breaker attempts recovery

Performance Considerations

  • Pagination: Use appropriate page sizes (10-50 items) to balance response time and data completeness

  • Automatic Retry: The server implements intelligent retry logic with:

    • Exponential backoff with jitter to prevent thundering herd

    • Circuit breaker pattern to prevent cascade failures

    • Retry budget to limit resource consumption

    • Respect for Retry-After headers from the API

  • Rate Limits: Rate-limited requests (429) are automatically retried with appropriate delays

  • Fault Tolerance: Transient failures (network, 502, 503, 504) are handled gracefully

  • Caching: Results are not cached. Consider implementing caching for frequently accessed data

Available Tools

1. projects

List all available DeepSource projects.

Parameters: None

Example Response:

[
  {
    "key": "https://api-key@app.deepsource.com",
    "name": "my-python-project"
  }
]

2. project_issues

Get issues from a DeepSource project with filtering and pagination.

Parameter

Type

Required

Description

projectKey

string

Yes

The unique identifier for the DeepSource project

first

number

No

Number of items to return (forward pagination)

after

string

No

Cursor for forward pagination

last

number

No

Number of items to return (backward pagination)

before

string

No

Cursor for backward pagination

path

string

No

Filter issues by file path

analyzerIn

string[]

No

Filter by analyzers (e.g., ["python", "javascript"])

tags

string[]

No

Filter by issue tags

Example Response:

{
  "issues": [
    {
      "id": "T2NjdXJyZW5jZTpnZHlqdnlxZ2E=",
      "title": "Avoid using hardcoded credentials",
      "shortcode": "PY-D100",
      "category": "SECURITY",
      "severity": "CRITICAL",
      "file_path": "src/config.py",
      "line_number": 42
    }
  ],
  "totalCount": 15,
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "YXJyYXljb25uZWN0aW9uOjQ="
  }
}

3. runs

List analysis runs for a project with filtering.

Parameter

Type

Required

Description

projectKey

string

Yes

The unique identifier for the DeepSource project

first

number

No

Number of items to return (forward pagination)

after

string

No

Cursor for forward pagination

last

number

No

Number of items to return (backward pagination)

before

string

No

Cursor for backward pagination

analyzerIn

string[]

No

Filter by analyzers

4. run

Get details of a specific analysis run.

Parameter

Type

Required

Description

projectKey

string

Yes

The unique identifier for the DeepSource project

runIdentifier

string

Yes

The runUid (UUID) or commitOid (commit hash)

isCommitOid

boolean

No

Whether runIdentifier is a commit hash (default: false)

5. recent_run_issues

Get issues from the most recent analysis run on a branch.

Parameter

Type

Required

Description

projectKey

string

Yes

The unique identifier for the DeepSource project

branchName

string

Yes

The branch name

first

number

No

Number of items to return

after

string

No

Cursor for forward pagination

6. dependency_vulnerabilities

Get security vulnerabilities in project dependencies.

Parameter

Type

Required

Description

projectKey

string

Yes

The unique identifier for the DeepSource project

first

number

No

Number of items to return

after

string

No

Cursor for forward pagination

Example Response:

{
  "vulnerabilities": [
    {
      "id": "VUL-001",
      "package": "requests",
      "version": "2.25.0",
      "severity": "HIGH",
      "cve": "CVE-2021-12345",
      "description": "Remote code execution vulnerability"
    }
  ],
  "totalCount": 3
}

7. quality_metrics

Get code quality metrics with optional filtering.

Parameter

Type

Required

Description

projectKey

string

Yes

The unique identifier for the DeepSource project

shortcodeIn

string[]

No

Filter by metric codes (see below)

Available Metrics:

  • LCV - Line Coverage

  • BCV - Branch Coverage

  • DCV - Documentation Coverage

  • DDP - Duplicate Code Percentage

  • SCV - Statement Coverage

  • TCV - Total Coverage

  • CMP - Code Maturity

8. update_metric_threshold

Update the threshold for a quality metric.

Parameter

Type

Required

Description

projectKey

string

Yes

The unique identifier for the DeepSource project

repositoryId

string

Yes

The GraphQL repository ID

metricShortcode

string

Yes

The metric shortcode (e.g., "LCV")

metricKey

string

Yes

The language or context key

thresholdValue

number|null

No

New threshold value, or null to remove

9. update_metric_setting

Update metric reporting and enforcement settings.

Parameter

Type

Required

Description

projectKey

string

Yes

The unique identifier for the DeepSource project

repositoryId

string

Yes

The GraphQL repository ID

metricShortcode

string

Yes

The metric shortcode

isReported

boolean

Yes

Whether to report this metric

isThresholdEnforced

boolean

Yes

Whether to enforce thresholds

10. compliance_report

Get security compliance reports.

Parameter

Type

Required

Description

projectKey

string

Yes

The unique identifier for the DeepSource project

reportType

string

Yes

Type of report (see below)

Available Report Types:

  • OWASP_TOP_10 - Web application security vulnerabilities

  • SANS_TOP_25 - Most dangerous software errors

  • MISRA_C - Guidelines for safety-critical C code

  • CODE_COVERAGE - Code coverage report

  • CODE_HEALTH_TREND - Quality trends over time

  • ISSUE_DISTRIBUTION - Issue categorization

  • ISSUES_PREVENTED - Prevented issues count

  • ISSUES_AUTOFIXED - Auto-fixed issues count

Usage Examples

Track your project's quality metrics over time:

"Show me the code coverage trend for my main branch"

This combines multiple tools to:

  1. Get recent runs for the main branch

  2. Retrieve coverage metrics for each run

  3. Display the trend

Set Up Quality Gates

Implement quality gates for CI/CD:

"Set up quality gates: 80% line coverage, 0 critical security issues"

This will:

  1. Update the line coverage threshold to 80%

  2. Configure enforcement for the threshold

  3. Check current critical security issues

Investigate Security Vulnerabilities

Comprehensive security analysis:

"Analyze all security vulnerabilities in my project including dependencies"

This performs:

  1. Dependency vulnerability scan

  2. Code security issue analysis

  3. OWASP Top 10 compliance check

  4. Prioritized remediation suggestions

Code Review Assistance

Get AI-powered code review insights:

"What are the most critical issues in the recent commits to feature/new-api?"

This will:

  1. Find the most recent run on the branch

  2. Filter for critical and high severity issues

  3. Group by file and issue type

  4. Suggest fixes

Team Productivity Metrics

Track team code quality metrics:

"Show me code quality metrics across all our Python projects"

This aggregates:

  1. Coverage metrics per project

  2. Issue counts by severity

  3. Trends over the last month

  4. Team performance insights

Architecture

The DeepSource MCP Server uses modern TypeScript patterns for maintainability and type safety.

Key Components

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Claude/AI      │────▶│   MCP Server     │────▶│  DeepSource API │
│  Assistant      │◀────│  (TypeScript)    │◀────│   (GraphQL)     │
└─────────────────┘     └──────────────────┘     └─────────────────┘
  1. MCP Server Integration (src/index.ts)

    • Registers and implements tool handlers

    • Manages MCP protocol communication

    • Handles errors and logging

  2. DeepSource Client (src/deepsource.ts)

    • GraphQL API communication

    • Authentication and retry logic

    • Response parsing and validation

  3. Type System (src/types/)

    • Branded types for type safety

    • Discriminated unions for state management

    • Zod schemas for runtime validation

Type Safety Features

Branded Types

// Prevent mixing different ID types
type ProjectKey = string & { readonly __brand: 'ProjectKey' };
type RunId = string & { readonly __brand: 'RunId' };

Discriminated Unions

type RunState =
  | { status: 'PENDING'; queuePosition?: number }
  | { status: 'SUCCESS'; finishedAt: string }
  | { status: 'FAILURE'; error?: { message: string } };

Development

Prerequisites

  • Node.js 22.19.0 or higher

  • pnpm 10.15.1 or higher

  • Docker (optional, for container builds)

Setup

# Clone the repository
git clone https://github.com/sapientpants/deepsource-mcp-server.git
cd deepsource-mcp-server

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run tests
pnpm test

Development Commands

Note: MCP servers communicate via stdio and cannot be run standalone. Use pnpm run inspect for interactive debugging.

Command

Description

pnpm install

Install dependencies

pnpm run build

Build TypeScript code

pnpm run watch

Build in watch mode

pnpm run clean

Remove build artifacts

pnpm run inspect

Debug with MCP Inspector

pnpm test

Run all tests

pnpm test:watch

Run tests in watch mode

pnpm test:coverage

Generate coverage report

pnpm run lint

Check for linting issues

pnpm run lint:fix

Fix linting issues

pnpm run format

Check code formatting

pnpm run format:fix

Fix code formatting

pnpm run check-types

TypeScript type checking

pnpm run ci

Run full CI pipeline

Troubleshooting & FAQ

Common Issues

Authentication Error

Error: Invalid API key or unauthorized access

Solution: Verify your DEEPSOURCE_API_KEY is correct and has necessary permissions.

No Projects Found

Error: No projects found

Solution: Ensure your API key has access to at least one project in DeepSource.

Rate Limit Exceeded

Error: API rate limit exceeded

Solution: The server implements automatic retry. Wait a moment or reduce request frequency.

Pagination Cursor Invalid

Error: Invalid cursor for pagination

Solution: Cursors expire. Start a new pagination sequence from the beginning.

FAQ

Q: Which DeepSource plan do I need? A: The MCP server works with all DeepSource plans. Some features like security compliance reports may require specific plan features.

Q: Can I use this with self-hosted DeepSource? A: Yes, configure the API endpoint in your environment variables (feature coming in v1.3.0).

Q: How do I debug issues? A: Enable debug logging by setting LOG_LEVEL=DEBUG and check the log file specified in LOG_FILE.

Q: Is my API key secure? A: The API key is only stored in your local Claude Desktop configuration and is never transmitted except to DeepSource's API.

Q: Can I contribute custom tools? A: Yes! See the Contributing section for guidelines.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Make your changes

  4. Run tests (pnpm test)

  5. Commit your changes using conventional commits (see below)

  6. Push to the branch (git push origin feature/amazing-feature)

  7. Open a Pull Request

Commit Message Convention

This project uses Conventional Commits to ensure consistent commit messages. Commits are validated using commitlint.

Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

  • feat: New feature

  • fix: Bug fix

  • docs: Documentation only changes

  • style: Changes that don't affect code meaning (formatting, etc)

  • refactor: Code change that neither fixes a bug nor adds a feature

  • perf: Performance improvements

  • test: Adding missing tests or correcting existing tests

  • build: Changes that affect the build system or dependencies

  • ci: Changes to CI configuration files and scripts

  • chore: Other changes that don't modify src or test files

  • revert: Reverts a previous commit

Examples

# Feature
git commit -m "feat: add support for filtering issues by severity"

# Bug fix with scope
git commit -m "fix(api): handle null response from DeepSource API"

# Breaking change
git commit -m "feat!: change API response format

BREAKING CHANGE: Response format now uses camelCase instead of snake_case"

Code Standards

  • Follow TypeScript best practices

  • Maintain test coverage above 80%

  • Use meaningful commit messages

  • Update documentation for new features

License

MIT - see LICENSE file for details.

External Resources


Made with ❤️ by the DeepSource MCP Server community

Available Tools

10 tools
compliance_reportA

Get security compliance reports from a DeepSource project

ParametersJSON Schema
NameRequiredDescriptionDefault
projectKeyYesDeepSource project key to identify the project
reportTypeYesType of compliance report to fetch

Output Schema

ParametersJSON Schema
NameRequiredDescription
keyYes
titleYes
currentValueYes
statusYes
securityIssueStatsYes
trendsNo
analysisYes
recommendationsYes

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only says 'Get', implying a read operation, but does not disclose any side effects, permissions, rate limits, or output behavior beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no unnecessary words. It is front-loaded with the verb and resource, making it easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and 100% parameter coverage, the description is minimally adequate. However, it lacks behavioral transparency and usage context, which are not compensated by other fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% – both 'projectKey' and 'reportType' are described in the input schema. The description adds no additional semantic information, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'security compliance reports from a DeepSource project'. It distinguishes this tool from siblings like 'dependency_vulnerabilities' and 'project_issues', which focus on different data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The description implies it's for compliance reports but does not specify when not to use it or mention other tools for similar purposes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

dependency_vulnerabilitiesB

Get dependency vulnerabilities from a DeepSource project

ParametersJSON Schema
NameRequiredDescriptionDefault
projectKeyYesDeepSource project key to fetch vulnerabilities for
firstNoNumber of items to retrieve (forward pagination)
afterNoCursor to start retrieving items after (forward pagination)
lastNoNumber of items to retrieve (backward pagination)
beforeNoCursor to start retrieving items before (backward pagination)
page_sizeNoNumber of items per page (alias for first, for convenience)
max_pagesNoMaximum number of pages to fetch (enables automatic multi-page fetching)

Output Schema

ParametersJSON Schema
NameRequiredDescription
vulnerabilitiesYes
pageInfoYes
totalCountYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits. It only states a read operation but omits details like pagination behavior, potential errors, or authentication needs, despite the schema hinting at pagination.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no wasted words. However, it is very brief and could be restructured to include more context efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (7 parameters, output schema, no annotations), the description is too minimal. It fails to explain the tool's purpose in a broader workflow or set expectations about pagination and project key usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond what the schema already provides for each parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get'), the resource ('dependency vulnerabilities'), and the scope ('from a DeepSource project'). This distinctly differentiates it from sibling tools like compliance_report or project_issues.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description lacks any context about prerequisites, exclusions, or comparative scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

project_issuesB

Get issues from a DeepSource project with filtering capabilities

ParametersJSON Schema
NameRequiredDescriptionDefault
projectKeyYesDeepSource project key to fetch issues for
pathNoFilter issues by file path
analyzerInNoFilter issues by analyzer shortcodes
tagsNoFilter issues by tags
firstNoNumber of items to retrieve (forward pagination)
afterNoCursor to start retrieving items after (forward pagination)
lastNoNumber of items to retrieve (backward pagination)
beforeNoCursor to start retrieving items before (backward pagination)
page_sizeNoNumber of items per page (alias for first, for convenience)
max_pagesNoMaximum number of pages to fetch (enables automatic multi-page fetching)

Output Schema

ParametersJSON Schema
NameRequiredDescription
issuesYes
pageInfoYes
paginationNoUser-friendly pagination metadata
totalCountYes

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description does not disclose pagination behavior, rate limits, or what the response contains. Without annotations, the description fails to inform about key behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded, but too brief; could be expanded to include key details without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 parameters including pagination, the description is insufficient; doesn't explain pagination cursor usage or filtering capabilities beyond the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% description coverage, so baseline is 3. Description adds no extra meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'Get' and resource 'issues from a DeepSource project', distinguishing it from sibling tools like compliance_report and dependency_vulnerabilities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs. alternatives, such as other issue-related tools (e.g., recent_run_issues). Lacks explicit context for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

projectsA

List all available DeepSource projects. Returns a list of project objects with "key" and "name" properties.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
projectsYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full responsibility. It transparently describes a read-only listing operation with no side effects. While simple, it fully discloses the behavior without omission.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the action ('List all available DeepSource projects') and follows with concise details. No extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, an output schema, and a straightforward task (listing projects), the description is complete. It covers the purpose and return format, and no additional context is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Since the input schema has no parameters (100% coverage), the description adds value by specifying the return structure (key and name properties). This exceeds the baseline of 4 for zero-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists all available DeepSource projects and specifies the return properties (key and name). This distinguishes it from sibling tools like compliance_report which focus on specific aspects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as compliance_report or project_issues. The description simply states the functionality without context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

quality_metricsB

Get quality metrics from a DeepSource project with optional filtering

ParametersJSON Schema
NameRequiredDescriptionDefault
projectKeyYesDeepSource project key to fetch quality metrics for
shortcodeInNoOptional filter for specific metric shortcodes

Output Schema

ParametersJSON Schema
NameRequiredDescription
metricsYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden. It only indicates a read operation ('Get') but does not disclose side effects, authentication requirements, rate limits, or any behavioral traits beyond that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence of 11 words. It is highly concise with no superfluous information, earning a top score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with 2 parameters and an output schema, so the description partially covers what is needed. However, it lacks context on prerequisites, how quality metrics relate to other sibling tools, or any performance implications. With output schema present, return values are covered, but overall completeness is average.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers 100% of parameters with descriptions, so the description adds minimal value ('optional filtering' is already implied by shortcodeIn). Baseline 3 is appropriate since the schema already explains the parameters adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get', the resource 'quality metrics', and the source 'DeepSource project'. It also mentions optional filtering, which adds clarity. However, it does not elaborate on what 'quality metrics' entail (e.g., code quality metrics), missing an opportunity to differentiate from siblings like dependency_vulnerabilities or project_issues.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus its siblings. The description mentions optional filtering but does not explain when filtering is appropriate or when alternative tools (e.g., for issues or vulnerabilities) should be used instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recent_run_issuesB

Get issues from the most recent analysis run on a specific branch

ParametersJSON Schema
NameRequiredDescriptionDefault
projectKeyYesDeepSource project key to fetch issues for
branchNameYesBranch name to fetch the most recent run from
firstNoNumber of items to retrieve (forward pagination)
afterNoCursor to start retrieving items after (forward pagination)
lastNoNumber of items to retrieve (backward pagination)
beforeNoCursor to start retrieving items before (backward pagination)
page_sizeNoNumber of items per page (alias for first, for convenience)
max_pagesNoMaximum number of pages to fetch (enables automatic multi-page fetching)

Output Schema

ParametersJSON Schema
NameRequiredDescription
runYes
issuesYes
pageInfoYes
totalCountYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. However, it only states a read-like operation without mentioning it is read-only, does not discuss authentication, rate limits, or pagination behavior. The description adds minimal value beyond the tool name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 9 words, extremely concise and front-loaded. Every word is necessary, and there is no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of 8 parameters including pagination, and the presence of an output schema, the description is minimal. It does not explain that only the latest run is considered, nor does it describe the order or filtering. Adequate for basic understanding but incomplete for nuanced usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already explains all parameters. The description does not add new meaning to any parameter beyond what the schema provides. Baseline score is 3 as description provides no additional semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves issues from the most recent analysis run on a specific branch. The verb 'Get' and resource 'issues' are specific, and the scope 'most recent analysis run on a specific branch' distinguishes it from siblings like 'project_issues' which likely list all issues.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as 'project_issues' or 'runs'. It does not mention when not to use it or provide context about prerequisites or limitations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

runB

Get a specific analysis run by its runUid or commitOid

ParametersJSON Schema
NameRequiredDescriptionDefault
projectKeyYesDeepSource project key to identify the project
runIdentifierYesThe run identifier (runUid or commitOid)
isCommitOidNoFlag to indicate whether the runIdentifier is a commitOid (default: false)

Output Schema

ParametersJSON Schema
NameRequiredDescription
runYes
analysisYes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description indicates a read-only operation ('Get'), which is consistent with the expected behavior. With no annotations provided, the description adequately conveys that it is a retrieval tool, but it does not disclose error handling or behavior when the run is not found.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that conveys the essential purpose. No unnecessary words, making it easy for the agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description does not need to explain return values. The description is sufficient for a simple getter tool, though it could be improved by mentioning that it returns a single run object. Overall, it is reasonably complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents the parameters. The description adds minimal value by restating that runIdentifier can be runUid or commitOid, but this is already encoded in the schema and the isCommitOid parameter. No additional semantic detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a specific analysis run using either runUid or commitOid. The verb 'Get' and the resource 'analysis run' are explicit. However, it does not explicitly differentiate from the sibling tool 'runs', which likely lists all runs, so clarity is good but not perfect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'runs' or other tools. There is no mention of prerequisites or context, leaving the agent to infer usage from the description alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

runsA

List analysis runs for a DeepSource project with filtering

ParametersJSON Schema
NameRequiredDescriptionDefault
projectKeyYesDeepSource project key to fetch runs for
analyzerInNoFilter runs by analyzer shortcodes
firstNoNumber of items to retrieve (forward pagination)
afterNoCursor to start retrieving items after (forward pagination)
lastNoNumber of items to retrieve (backward pagination)
beforeNoCursor to start retrieving items before (backward pagination)
page_sizeNoNumber of items per page (alias for first, for convenience)
max_pagesNoMaximum number of pages to fetch (enables automatic multi-page fetching)

Output Schema

ParametersJSON Schema
NameRequiredDescription
runsYes
pageInfoYes
totalCountYes

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden for behavioral disclosure. It does not mention pagination behavior, rate limits, or what happens on invalid projects. The schema includes cursor parameters (first, after, last, before, page_size, max_pages), but the description omits any behavioral context like automatic pagination or cursor-based pagination.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, clear sentence with no fluff. Every word is necessary and earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 8 parameters and no annotations, the description is minimal but combined with the schema is adequate. However, it lacks context on pagination behavior and does not differentiate from sibling tool 'run'. Output schema exists to describe return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with all parameters described. The description adds only 'with filtering', which is vague and does not provide additional meaning beyond the schema. Baseline score of 3 is appropriate as schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool lists analysis runs for a DeepSource project with filtering. It uses a specific verb (list) and resource (analysis runs), and distinguishes from sibling tools like 'run' (likely single run retrieval) and 'project_issues'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage for listing filtered runs, but does not explicitly state when not to use or mention alternatives. Context is clear, but no exclusions or comparisons to siblings are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_metric_settingC

Update the settings for a quality metric

ParametersJSON Schema
NameRequiredDescriptionDefault
projectKeyYesDeepSource project key to identify the project
repositoryIdYesRepository GraphQL ID
metricShortcodeYesCode for the metric to update
isReportedYesWhether the metric should be reported
isThresholdEnforcedYesWhether the threshold should be enforced

Output Schema

ParametersJSON Schema
NameRequiredDescription
okYes
projectKeyYes
metricShortcodeYes
settingsYes
messageYes
next_stepsYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It only says 'Update', implying mutation, but fails to state side effects, authorization requirements, or error conditions (e.g., what happens if the metric doesn't exist). This is insufficient for an agent to safely invoke the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no unnecessary words. It is front-loaded with the key verb and resource, making it efficient for scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the existence of an output schema, the description is too minimal. It does not explain the broader context of updating metric settings, such as the effect on reporting or enforcement, or how it relates to other metric tools. The five required parameters are left unexplained beyond the schema, which is insufficient for a complete understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema; it merely restates the generic 'settings' without explaining how the boolean parameters affect the metric. The agent must rely entirely on the parameter descriptions in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Update') and the resource ('settings for a quality metric'), which is sufficient to understand the basic purpose. However, it does not distinguish from the sibling tool 'update_metric_threshold', which might update a specific threshold value, so specificity is slightly lacking.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'update_metric_threshold'. The description does not mention context, prerequisites, or scenarios where this tool is appropriate, leaving the agent to infer usage from the schema alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_metric_thresholdC

Update the threshold for a specific quality metric

ParametersJSON Schema
NameRequiredDescriptionDefault
projectKeyYesDeepSource project key to identify the project
repositoryIdYesRepository GraphQL ID
metricShortcodeYesCode for the metric to update
metricKeyYesContext key for the metric
thresholdValueNoNew threshold value, or null to remove

Output Schema

ParametersJSON Schema
NameRequiredDescription
okYes
projectKeyYes
metricShortcodeYes
metricKeyYes
thresholdValueNo
messageYes
next_stepsYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations available, the description carries the full burden of disclosing behavioral traits. It only states 'update' which implies mutation but does not mention authorization needs, idempotency, side effects on other metrics, or whether setting threshold to null removes it. The description adds minimal value beyond the tool name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with only 8 words, containing no fluff or repetition. It efficiently communicates the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the tool (5 parameters, 4 required, mutation with no annotations) and the presence of an output schema, the description is too brief. It lacks details on the effect of null thresholdValue, the meaning of metricShortcode values, and the expected outcome. The existing output schema partially mitigates the need for return value explanation, but the description should provide more operational context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides full descriptions for all 5 parameters (100% coverage). The description does not add any additional meaning or context beyond what is in the schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action (update) and the object (threshold for a specific quality metric). It is specific enough to distinguish from sibling tools like update_metric_setting or quality_metrics, though it does not explicitly call out the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, nor are there any prerequisites or when-not-to-use conditions stated. The description simply states what it does without contextual usage advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

No tool schema history has been recorded yet.

TDQS

B3.4/5.0
Disambiguation4/5

Most tools have clearly distinct purposes (projects vs runs vs issues vs metrics vs security). However, project_issues and recent_run_issues both deal with issues and could cause initial confusion, though descriptions clarify the difference.

Naming Consistency4/5

Tool names follow a predictable pattern: query tools are named after the resource (noun or noun phrase, e.g., projects, runs, quality_metrics) and mutation tools use verb_resource (e.g., update_metric_setting). This is consistent and readable.

Tool Count5/5

10 tools is well-scoped for a code analysis server, covering core areas (projects, runs, issues, metrics, compliance, dependencies) without being overwhelming or too sparse.

Completeness3/5

The tool set covers most essential operations (list, get, update for key resources) but lacks branch listing (needed for recent_run_issues) and triggering analysis runs, which are notable gaps for a comprehensive interface.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    A
    maintenance
    A Model Context Protocol server that enhances AI agents by providing deep semantic understanding of codebases, enabling more intelligent interactions through advanced code search and contextual awareness.
    89
    MIT
  • -
    license
    B
    quality
    Not graded
    maintenance
    A Model Context Protocol server that enables AI assistants to fetch and understand GitHub repository documentation on-demand from DeepWiki during conversations.
    3
    -
  • A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server that analyzes application codebases with real-time file watching, providing AI assistants like Claude with deep insights into project structure, code patterns, and architecture.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sapientpants/deepsource-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server