Skip to main content
Glama
alexbypa

projectpulse-mcp

by alexbypa
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

This Model Context Protocol (MCP) server gives AI assistants the ability to analyze health, security, CI/CD status, and delivery metrics of any GitHub repository — directly from your conversations.

✨ Features

  • 🏥 Health Score — comprehensive 0-100 score with grade (A-F), category breakdown, and improvement suggestions

  • 🔒 Security — Dependabot alerts blended with OpenSSF Scorecard checks (60/40 weighted)

  • 📊 DORA Metrics — proxy DORA metrics from GitHub data: deployment frequency, lead time, change failure rate, MTTR

  • 🔍 Code Scanning — CodeQL and other code scanning alerts with severity, message, and creation date

  • 📦 Dependency Analysis — Dependabot alerts with severity filtering

  • ⚙️ CI/CD Status — recent GitHub Actions workflow runs and conclusions

  • 📋 Repository Info — stars, forks, language, license, and general metadata

Related MCP server: GitBridge

📸 Example

Code Scanning Example

🚀 Quick Start

Claude Code (CLI)

claude mcp add projectpulse -- npx projectpulse-mcp

Note: You need a .env file with your GITHUB_TOKEN in the directory where you run Claude Code.

Claude Desktop

Step 1: Get a GitHub Token

  1. Go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens

  2. Give it a name (e.g., projectpulse)

  3. Select the repositories you want to monitor (or "All repositories")

  4. Under Permissions, grant Read-only access to:

    • Code scanning alerts

    • Dependabot alerts

    • Metadata (enabled by default)

  5. Click Generate token and copy it

Step 2: Configure Claude Desktop

  1. Open Claude Desktop

  2. Go to Settings (gear icon) > Developer > Edit Config

  3. This opens claude_desktop_config.json. Add the projectpulse entry inside "mcpServers":

{
  "mcpServers": {
    "projectpulse": {
      "command": "npx",
      "args": ["-y", "projectpulse-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_paste_your_token_here"
      }
    }
  }
}

  1. Save the file and restart Claude Desktop

Step 3: Verify it works

In a new Claude Desktop conversation, try asking:

"Check the health score of facebook/react"

Claude should call the get_health_score tool and return an A-F grade with a detailed breakdown.

Troubleshooting

Problem

Solution

Tools not showing up

Restart Claude Desktop after editing the config file

"Rate limit exceeded" errors

Make sure GITHUB_TOKEN is set correctly in the config

Dependabot/CodeQL data missing

Your token needs Code scanning alerts and Dependabot alerts permissions

npx not found

Install Node.js (v18 or later) and make sure npx is in your PATH

Other MCP Clients (Cursor, Windsurf, etc.)

Configure a new MCP server with:

  • Transport: stdio

  • Command: npx

  • Arguments: -y projectpulse-mcp

  • Environment: GITHUB_TOKEN = your GitHub PAT

🛠️ Tools

get_health_score

Calculates a 0-100 health score with an A-F grade. Evaluates 5 weighted categories: CI reliability (25%), code freshness (20%), security posture (25%), community activity (15%), and maintenance quality (15%). Returns actionable improvement suggestions for low-scoring categories. On repeated calls for the same repo, includes a trend comparison showing score change since last check. Queries multiple GitHub API endpoints and OpenSSF Scorecard.

Side effect: saves a trend snapshot to local disk (~/.projectpulse/snapshots/).

Inputs: owner, repo Try asking: "What's the health score of microsoft/vscode?"

get_dora_metrics

Calculates proxy DORA metrics from public GitHub data: Deployment Frequency (from releases), Lead Time for Changes (PR created → merged), Change Failure Rate (CI failure percentage), and Mean Time to Recovery (CI failure → next success). Returns null for metrics with insufficient data. Queries multiple GitHub API endpoints (releases, pulls, actions) — heavier API usage than single-endpoint tools.

Inputs: owner, repo, days (optional, 7-90, default 30) Try asking: "Show me the DORA metrics for vercel/next.js over the last 60 days"

compare_repos

Compares health scores side-by-side for 2-5 repositories. Returns each repo's full health breakdown ranked by score. Useful for evaluating alternatives or benchmarking your project against similar ones. API calls are multiplied by the number of repos compared.

Inputs: repos (array of {owner, repo}) Try asking: "Compare the health of expressjs/express, fastify/fastify, and koajs/koa"

get_repo_health

Fetches basic repository metadata: stars, forks, open issues count, primary language, license, last push date, default branch, and archive status. Use this for a quick overview — for a computed grade, use get_health_score instead.

Inputs: owner, repo Try asking: "Give me general info about torvalds/linux"

analyze_dependencies

Lists Dependabot security alerts for vulnerable package dependencies (npm, pip, Maven, etc.) grouped by severity (critical, high, medium, low). Optionally filter by a specific severity level. Requires a token with Dependabot alerts permission.

Inputs: owner, repo, severity (optional) Try asking: "Show me critical dependency vulnerabilities in my-org/my-app"

check_ci_status

Returns the most recent CI/CD workflow runs from GitHub Actions: status (success, failure, in_progress), conclusion, branch, duration, and timestamps. Useful for checking if builds are green before deploying or merging.

Inputs: owner, repo, limit (optional, default 10) Try asking: "Are the CI builds passing for facebook/react?"

analyze_code_scanning

Lists CodeQL and other code scanning alerts: rule ID, severity, vulnerability message, affected file and line number, and creation date. Requires a token with Code scanning alerts permission. Can optionally trigger a CodeQL scan and wait for results (requires Advanced Setup, not Default Setup).

Inputs: owner, repo, trigger_scan (optional, default false), poll_timeout_seconds (optional, default 300), poll_interval_seconds (optional, default 15) Try asking: "Are there any code scanning vulnerabilities in my-org/my-api?"

ping

Simple connectivity check. Returns "pong" with your message. Use to verify the MCP server is running.

Inputs: message

🆕 What's New

OpenSSF Scorecard Integration

Security score now blends Dependabot alerts (60%) with OpenSSF Scorecard checks (40%) for a more complete picture. 12 security-relevant checks are evaluated — repos without a scorecard gracefully fall back to Dependabot-only scoring.

DORA Metrics

New get_dora_metrics tool calculates proxy DORA metrics from public GitHub data:

Metric

Source

Unit

Deployment Frequency

Releases

releases/week

Lead Time for Changes

PR created → merged

hours (median)

Change Failure Rate

CI workflow conclusions

percentage

Mean Time to Recovery

CI failure → next success

hours (median)

Metrics return null when insufficient data is available — works safely on any repository.

⚙️ Configuration

GITHUB_TOKEN

Required to avoid rate limits and access security data (Dependabot, CodeQL alerts).

Option A: Fine-grained PAT (Recommended)

  1. Settings > Developer settings > Personal access tokens > Fine-grained tokens

  2. Select target repositories

  3. Grant Read-only access to:

    • Code scanning alerts

    • Dependabot alerts

    • Metadata (default)

Option B: Classic Token Generate with repo + security_events scopes.

Providing the token:

  • Claude Desktop: set in claude_desktop_config.json (see Quick Start)

  • Claude Code / Local: create a .env file:

    GITHUB_TOKEN=ghp_your_token_here

👤 Author

alexbypa — GitHub · npm

🤝 Contributing

Contributions, issues and feature requests are welcome! Feel free to check the issues page.

⭐ Show your support

Give a star if this project helped you!

📝 License

MIT — see the LICENSE file for details.

Available Tools

7 tools
analyze_code_scanningA

Fetches or triggers open Code Scanning (CodeQL) alerts for a GitHub repository.

  • Side effects: Read-only by default. If trigger_scan=true, writes to GitHub Actions by creating a workflow_dispatch event.

  • Data sources: GitHub REST API (code-scanning/alerts and actions).

  • Auth requirements: Requires GITHUB_TOKEN with appropriate permissions (security-events).

  • Rate limits: Subject to standard GitHub API limits.

  • Return shape: Returns a JSON array of alert objects including rule_id, severity, rule_description, state, location paths, and html_url.

  • Usage guidelines: Use this tool ONLY for deep static code vulnerability scanning (CodeQL). DO NOT use this tool for other checks:

    • For package/dependency vulnerabilities, use 'analyze_dependencies' instead.

    • For a computed A-F health score grading, use 'get_health_score' instead.

    • For checking standard CI/CD workflow statuses, use 'check_ci_status' instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoYesGitHub repository name (e.g., 'sdk')
ownerYesGitHub repository owner (e.g., 'modelcontextprotocol')
trigger_scanNoIf true, triggers CodeQL workflow then polls for results before returning alerts
poll_timeout_secondsNoMax seconds to wait for CodeQL scan completion (default 300)
poll_interval_secondsNoSeconds between poll attempts (default 15)

Output Schema

ParametersJSON Schema
NameRequiredDescription
alertsYes
warningNo

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations, the description fully discloses the conditional side effect: 'Read-only by default. If trigger_scan=true, writes to GitHub Actions by creating a workflow_dispatch event.' It also adds auth requirements, rate limit awareness, and return shape, which is substantial behavioral context. The annotations are consistent: readOnlyHint=false correctly reflects the optional write behavior.

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 structured with clear bullets and front-loads the core purpose before side effects, data sources, auth, return shape, and usage guidance. Every section earns its place and is written efficiently for an agent to consume.

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?

For a tool with 5 parameters, annotations, an output schema, and sibling tools, the description is exceptionally complete. It covers side effects, auth, rate limits, return shape, polling behavior, and explicit routing to alternatives. No critical operational context is missing for an agent to select and invoke this tool correctly.

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 schema has 100% parameter description coverage, so the baseline is appropriately 3. The description adds minimal extra parameter meaning beyond what the schema already provides, though the side-effect explanation for trigger_scan is helpful. It does not meaningfully enhance understanding of owner, repo, poll_timeout_seconds, or poll_interval_seconds beyond the schema.

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 tool's specific verb and resource: 'Fetches or triggers open Code Scanning (CodeQL) alerts for a GitHub repository.' This distinguishes it from the available sibling tools, especially when combined with the explicit usage guidelines naming alternatives.

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

Usage Guidelines5/5

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

The description explicitly narrows usage to 'deep static code vulnerability scanning (CodeQL)' and gives direct exclusions with sibling alternatives: analyze_dependencies for package vulnerabilities, get_health_score for A-F grading, and check_ci_status for CI/CD statuses. This is explicit when-to-use and when-not-to-use guidance.

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

analyze_dependenciesA
Read-onlyIdempotent

Fetches Dependabot alerts for a GitHub repository to analyze vulnerable package dependencies.

  • Side effects: None. This is a strictly read-only operation.

  • Data sources: GitHub REST API (dependabot/alerts).

  • Auth requirements: Requires GITHUB_TOKEN with appropriate permissions (dependabot alerts are often restricted).

  • Rate limits: Subject to standard GitHub API limits.

  • Return shape: Returns a JSON array of vulnerable package dependencies including summary, severity, package_name, state, and html_url.

  • Usage guidelines: Use this tool ONLY to find vulnerable package dependencies (npm, pip, etc.). DO NOT use this tool for other checks:

    • For static code security vulnerabilities (CodeQL), use 'analyze_code_scanning' instead.

    • For a computed A-F health score grading, use 'get_health_score' instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoYesGitHub repository name (e.g., 'sdk')
ownerYesGitHub repository owner (e.g., 'modelcontextprotocol')
severityNo

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already mark the tool as read-only and non-destructive, but the description adds valuable behavioral context: no side effects, data source (GitHub REST API dependabot/alerts), auth requirements, rate limits, and return shape. No contradiction exists between the description and annotations.

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 front-loaded with the core purpose and then uses compact labeled bullets for side effects, data source, auth, rate limits, return shape, and usage guidelines. Every sentence adds useful information without redundancy.

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?

Despite lacking an output schema, the description explicitly states the return shape including fields like summary, severity, package_name, state, and html_url. It also covers auth, rate limits, and sibling tool exclusions, making it complete for an agent to invoke correctly.

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 67%, so the schema already documents most parameters. The description does not add parameter-level guidance, such as how the severity parameter filters results. It mentions severity only as a return field, which could be slightly ambiguous, so the description provides no meaningful parameter clarification beyond the schema.

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 opens with a specific verb and resource: 'Fetches Dependabot alerts for a GitHub repository to analyze vulnerable package dependencies.' It clearly distinguishes this tool from siblings like analyze_code_scanning by scoping it to vulnerable package dependencies rather than static code vulnerabilities.

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

Usage Guidelines5/5

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

The description explicitly states when to use the tool ('ONLY to find vulnerable package dependencies') and when not to use it, naming alternatives: analyze_code_scanning for CodeQL and get_health_score for health grading. This provides unambiguous routing guidance.

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

check_ci_statusA
Read-onlyIdempotent

Fetches recent CI/CD workflow runs (GitHub Actions) for a GitHub repository.

  • Side effects: None. This is a strictly read-only operation.

  • Data sources: GitHub REST API (actions/runs).

  • Auth requirements: No authentication required for public repositories. Uses configured token if available.

  • Rate limits: Subject to standard GitHub API limits.

  • Return shape: Returns a JSON array of workflow runs including name, status, conclusion, head_branch, created_at, updated_at, and html_url.

  • Usage guidelines: Use this tool ONLY to check raw GitHub Actions workflow history and CI build statuses. DO NOT use this tool for other analyses:

    • For a computed A-F health score grading, use 'get_health_score' instead.

    • For retrieving basic repository stats (stars, forks), use 'get_repo_health' instead.

    • For calculated DORA metrics, use 'get_dora_metrics' instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoYesGitHub repository name (e.g., 'sdk')
limitNoNumber of runs to return
ownerYesGitHub repository owner (e.g., 'modelcontextprotocol')

TDQS

A4.7/5.0
Behavior5/5

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

The description thoroughly discloses side effects, data sources, auth requirements, rate limits, and return shape. This goes well beyond the annotations, which only indicate readOnly, openWorld, idempotent, and non-destructive behavior. No contradiction with annotations exists.

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 well-structured with a front-loaded purpose, followed by concise bullet points for side effects, data sources, auth, rate limits, return shape, and usage guidelines. Each section adds distinct value, and the exclusion list is efficient rather than redundant.

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 the tool has no output schema, the description compensates by specifying the return shape precisely. It also covers auth, rate limits, side effects, and alternatives, making the description fully complete for an agent to select and invoke the tool correctly.

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 fully documents the three parameters. The description adds context about the returned fields but does not add much meaning about the parameters themselves, which matches the baseline for high schema coverage.

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 opens with a specific verb and resource: 'Fetches recent CI/CD workflow runs (GitHub Actions) for a GitHub repository.' It clearly distinguishes the tool from siblings by explicitly naming what it is for and what it is not for, such as get_health_score and get_dora_metrics.

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

Usage Guidelines5/5

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

The description provides explicit usage guidelines: 'Use this tool ONLY to check raw GitHub Actions workflow history and CI build statuses.' It then lists specific alternative tools for other analyses, leaving no ambiguity about when to choose this tool versus siblings.

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

compare_reposA
Read-onlyIdempotent

Compares health scores of multiple GitHub repositories (2-5 repos) and ranks them.

  • Side effects: None. This is a strictly read-only operation.

  • Data sources: GitHub REST API and OpenSSF Scorecard API (via get_health_score logic).

  • Auth requirements: No authentication required for public repositories. Uses configured token if available.

  • Rate limits: Subject to standard GitHub API limits. Multiplies API calls by the number of repositories compared.

  • Return shape: Returns a JSON object containing a ranked list of repositories (owner, repo, rank) with their detailed health breakdown (score, CI, freshness, security, community, maintenance).

  • Usage guidelines: Use this tool ONLY when you need to compare or rank multiple repositories against each other based on their health scores. DO NOT use this tool for analyzing a single repository:

    • For getting the health score of a single repository, use 'get_health_score' instead.

    • For comparing raw metadata instead of health scores, query 'get_repo_health' individually.

ParametersJSON Schema
NameRequiredDescriptionDefault
reposYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
reposYes
compared_atYes

TDQS

A4.8/5.0
Behavior5/5

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

The description thoroughly discloses behavior beyond the annotations: explicitly states 'Side effects: None', specifies data sources (GitHub REST API and OpenSSF Scorecard API), explains auth requirements, and warns about rate-limit multiplication. This aligns with annotations (readOnlyHint=true, destructiveHint=false) and adds meaningful operational context.

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 structured with clear bullet points and front-loads the core purpose in the first sentence. It is longer than average, but nearly every line carries useful information about side effects, data sources, auth, rate limits, return shape, and usage boundaries. Minor redundancy exists between 'Side effects: None' and 'strictly read-only', but it does not detract significantly.

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?

For a tool that calls external APIs and compares multiple repositories, the description is complete: it covers data sources, authentication, rate-limit implications, exact repository count limits, return shape, and clear routing to sibling tools. Nothing needed to invoke it correctly is missing.

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?

Schema description coverage is 0%, so the description carries the burden. It compensates by stating the accepted count range (2-5 repos), the comparison/ranking behavior, and the output shape. The nested owner/repo properties are documented in the schema itself, so the description adds enough context for correct parameter use.

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 opens with a specific verb and resource: 'Compares health scores of multiple GitHub repositories (2-5 repos) and ranks them.' It clearly identifies the operation and scope, and the explicit comparison/ranking focus distinguishes it from sibling tools like get_health_score and get_repo_health.

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

Usage Guidelines5/5

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

The description gives explicit when-to-use guidance: 'Use this tool ONLY when you need to compare or rank multiple repositories.' It also provides strong guardrails with 'DO NOT use this tool for analyzing a single repository' and names the correct alternatives: get_health_score for single-repo health and get_repo_health for raw metadata comparison.

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

get_dora_metricsA
Read-onlyIdempotent

Calculates DORA proxy metrics (deployment frequency, lead time, change failure rate, MTTR) for a GitHub repository.

  • Side effects: None. This is a strictly read-only operation.

  • Data sources: GitHub REST API (releases, actions/runs, pulls).

  • Auth requirements: No special authentication required for public repositories. Private repositories require GITHUB_TOKEN.

  • Rate limits: Subject to standard GitHub API limits. Heavy API usage due to multiple list endpoints being queried.

  • Return shape: Returns a JSON object with calculated DORA metrics over the specified period.

  • Usage guidelines: Use this tool ONLY to evaluate DORA metrics and team delivery performance. DO NOT use this tool for other checks:

    • For raw workflow statuses, use 'check_ci_status' instead.

    • For a computed A-F health score grading, use 'get_health_score' instead.

    • For general repository metadata, use 'get_repo_health' instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNoNumber of past days to analyze (default: 30)
repoYesGitHub repository name (e.g., 'sdk')
ownerYesGitHub repository owner (e.g., 'modelcontextprotocol')

Output Schema

ParametersJSON Schema
NameRequiredDescription
mttrYes
repoYes
ownerYes
lead_timeYes
measured_toYes
period_daysYes
measured_fromYes
change_failure_rateYes
deployment_frequencyYes

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the readOnly/idempotent/destructive annotations, the description adds concrete behavioral detail: no side effects, GitHub REST API data sources, public vs. private auth requirements, standard API rate limits, and heavy multi-endpoint API usage. This is exactly the kind of context that helps the agent predict cost and failure modes.

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 uses compact bullet points with the core purpose first, followed by behavior, constraints, return shape, and usage routing. Each section adds distinct information; the only mild redundancy is 'Side effects: None' alongside 'strictly read-only,' but this does not meaningfully bloat the definition.

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?

For a moderately complex metrics tool with an output schema, the description covers purpose, exclusions, auth, rate limits, data sources, side effects, and return shape. Combined with the fully described input schema and annotations, there are no significant gaps an agent would need to guess about.

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%, and each property (days, repo, owner) already has a clear schema description with defaults and examples. The tool description does not add parameter-specific detail, but with full schema coverage it has no obligation to; 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 opens with a specific verb and resource: 'Calculates DORA proxy metrics (deployment frequency, lead time, change failure rate, MTTR) for a GitHub repository.' It names the exact metrics and scope, and the usage-guidelines section explicitly separates it from sibling tools, so an agent can distinguish it immediately.

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

Usage Guidelines5/5

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

The description gives unambiguous when-to-use guidance: 'Use this tool ONLY to evaluate DORA metrics and team delivery performance.' It also provides explicit not-this-tool routing for check_ci_status, get_health_score, and get_repo_health, making the selection decision clear without requiring the agent to infer.

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

get_health_scoreA
Idempotent

Calculates a 0-100 health score and A-F grade for a GitHub repository.

  • Side effects: Writes a trend snapshot to local disk for history tracking. Read-only against GitHub API.

  • Data sources: GitHub REST API (repos, actions, dependabot) and OpenSSF Scorecard API.

  • Auth requirements: No authentication required for public repositories. Uses configured token if available.

  • Rate limits: Subject to standard GitHub API limits (heavy usage across multiple endpoints).

  • Return shape: Returns a JSON object with a grade (A-F), total score, detailed category breakdown (CI, freshness, security, community, maintenance), improvement suggestions, and historical trend data.

  • Usage guidelines: Use this tool ONLY for deep analytical grading and overall repository health assessment. DO NOT use this tool for quick metadata checks:

    • For basic raw metadata (stars, language, etc.), use 'get_repo_health' instead.

    • For raw CI workflow statuses, use 'check_ci_status' instead.

    • For deep code vulnerability scanning, use 'analyze_code_scanning' instead.

    • For DORA metrics, use 'get_dora_metrics' instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoYesGitHub repository name (e.g., 'sdk')
ownerYesGitHub repository owner (e.g., 'modelcontextprotocol')

Output Schema

ParametersJSON Schema
NameRequiredDescription
trendYes
reportYes

TDQS

A4.7/5.0
Behavior5/5

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

The description discloses side effects ('Writes a trend snapshot to local disk'), data sources (GitHub REST API and OpenSSF Scorecard API), auth requirements, and rate limits. It also details the exact return shape with category breakdown, suggestions, and historical trend data. This goes well beyond the sparse boolean annotations.

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 organized into labeled bullet sections (Side effects, Data sources, Auth requirements, Rate limits, Return shape, Usage guidelines) with the core purpose front-loaded. Every section conveys non-redundant, decision-relevant information, so the length is justified.

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?

The description covers purpose, alternatives, side effects, data sources, auth, rate limits, and return shape, leaving no operational gaps. The presence of an output schema further reduces the need to explain return values, yet the description still provides a helpful summary.

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?

Both parameters repo and owner are fully described in the input schema with examples, yielding 100% schema description coverage. The description adds context about public vs. protected repositories but no additional parameter-level detail, so the baseline 3 applies.

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 opener 'Calculates a 0-100 health score and A-F grade for a GitHub repository' names a specific verb, resource, and output. The later guidance 'Use this tool ONLY for deep analytical grading and overall repository health assessment' explicitly differentiates it from siblings like get_repo_health and check_ci_status. Unambiguous and distinctive.

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

Usage Guidelines5/5

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

The description provides explicit when-to-use guidance: 'Use this tool ONLY for deep analytical grading... DO NOT use this tool for quick metadata checks.' It then lists four sibling alternatives with precise conditions, e.g., 'For basic raw metadata (stars, language, etc.), use get_repo_health instead.' No inference is needed.

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

get_repo_healthA
Read-onlyIdempotent

Fetches basic repository metadata and statistics from the public GitHub API.

  • Side effects: None. This is a strictly read-only operation.

  • Data sources: Public GitHub REST API (GET /repos/{owner}/{repo}).

  • Auth requirements: No authentication required for public repositories. Uses configured GitHub token if available.

  • Rate limits: Subject to standard GitHub API limits (60 requests/hour unauthenticated, 5000 requests/hour authenticated).

  • Return shape: Returns a JSON object containing specific metadata: full_name (string), description (string), stargazers_count (number), open_issues_count (number), language (string), license (string, SPDX ID), pushed_at (ISO 8601 string), default_branch (string), archived (boolean), and forks_count (number).

  • Usage guidelines: Use this tool ONLY to retrieve basic raw metadata (like stars, forks, language, and issue counts). DO NOT use this tool for other specific analyses:

    • For a computed A-F health score grading, use 'get_health_score' instead.

    • For checking CI/CD workflow run statuses, use 'check_ci_status' instead.

    • For package vulnerabilities and dependency graph, use 'analyze_dependencies' instead.

    • For code security and static analysis, use 'analyze_code_scanning' instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoYesGitHub repository name (e.g., 'sdk')
ownerYesGitHub repository owner (e.g., 'modelcontextprotocol')

Output Schema

ParametersJSON Schema
NameRequiredDescription
licenseYes
archivedYes
languageYes
full_nameYes
pushed_atYes
descriptionYes
forks_countYes
default_branchYes
stargazers_countYes
open_issues_countYes

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable context: side effects are explicitly none, auth requirements are stated (public repos need no auth, token used if available), rate limits are quantified, and the underlying endpoint is identified. No contradictions with annotations.

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 well-organized with the primary purpose front-loaded and the rest in scannable bullet points. However, the 'Return shape' section largely duplicates the output schema, which adds length without new information. The sibling exclusions are valuable and justify the overall length.

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?

The description covers data source, auth requirements, rate limits, return shape, and explicit routing to alternatives. Combined with the annotations and output schema, nothing critical is missing for an agent to select and invoke this tool correctly.

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 has 100% coverage with clear descriptions for both 'owner' and 'repo' parameters. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline 3 applies.

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 uses a specific verb ('Fetches') and resource ('basic repository metadata and statistics from the public GitHub API'), clearly identifying what the tool does. The usage guidelines further differentiate it from siblings by noting it returns raw metadata rather than a computed health score.

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

Usage Guidelines5/5

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

The description explicitly states when to use the tool ('ONLY to retrieve basic raw metadata') and when not to, naming each sibling tool and the exact purpose for which it should be used instead. This leaves no ambiguity about tool selection.

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.

  1. 5 tool updatesv1.1.7
    • Changedanalyze_code_scanning1 field changed
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "alerts": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "alert_number": {
+            "type": "number"
+          },
+          "created_at": {
+            "type": "string"
+          },
+          "end_line": {
+            "type": "number"
+          },
+          "html_url": {
+            "type": "string"
+          },
+          "message_text": {
+            "type": "string"
+          },
+          "most_recent_instance_path": {
+            "type": "string"
+          },
+          "most_recent_instance_start_line": {
+            "type": "number"
+          },
+          "rule_description": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "rule_id": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "severity": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "state": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "rule_id",
+          "severity",
+          "rule_description",
+          "state",
+          "html_url",
+          "alert_number",
+          "created_at"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "warning": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "alerts"
+  ],
+  "type": "object"
+}
    • Changedcompare_repos1 field changed
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "compared_at": {
+      "type": "string"
+    },
+    "repos": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "error": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "health": {
+            "anyOf": [
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "breakdown": {
+                    "additionalProperties": {
+                      "additionalProperties": false,
+                      "properties": {
+                        "detail": {
+                          "type": "string"
+                        },
+                        "score": {
+                          "type": "number"
+                        },
+                        "weight": {
+                          "type": "number"
+                        }
+                      },
+                      "required": [
+                        "score",
+                        "weight",
+                        "detail"
+                      ],
+                      "type": "object"
+                    },
+                    "propertyNames": {
+                      "type": "string"
+                    },
+                    "type": "object"
+                  },
+                  "checkedAt": {
+                    "type": "string"
+                  },
+                  "grade": {
+                    "type": "string"
+                  },
+                  "gradeMeaning": {
+                    "type": "string"
+                  },
+                  "repo": {
+                    "type": "string"
+                  },
+                  "score": {
+                    "type": "number"
+                  },
+                  "suggestions": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  }
+                },
+                "required": [
+                  "repo",
+                  "score",
+                  "grade",
+                  "breakdown",
+                  "suggestions",
+                  "checkedAt",
+                  "gradeMeaning"
+                ],
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "owner": {
+            "type": "string"
+          },
+          "rank": {
+            "type": "number"
+          },
+          "repo": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "owner",
+          "repo",
+          "rank",
+          "health",
+          "error"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "compared_at",
+    "repos"
+  ],
+  "type": "object"
+}
    • Changedget_dora_metrics1 field changed
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "change_failure_rate": {
+      "additionalProperties": false,
+      "properties": {
+        "failed_runs": {
+          "type": "number"
+        },
+        "rate_percent": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "total_runs": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "total_runs",
+        "failed_runs",
+        "rate_percent"
+      ],
+      "type": "object"
+    },
+    "deployment_frequency": {
+      "additionalProperties": false,
+      "properties": {
+        "per_week": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "releases_count": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "releases_count",
+        "per_week"
+      ],
+      "type": "object"
+    },
+    "lead_time": {
+      "additionalProperties": false,
+      "properties": {
+        "median_hours": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "pr_count": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "median_hours",
+        "pr_count"
+      ],
+      "type": "object"
+    },
+    "measured_from": {
+      "type": "string"
+    },
+    "measured_to": {
+      "type": "string"
+    },
+    "mttr": {
+      "additionalProperties": false,
+      "properties": {
+        "incidents_count": {
+          "type": "number"
+        },
+        "median_hours": {
+          "type": [
+            "number",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "median_hours",
+        "incidents_count"
+      ],
+      "type": "object"
+    },
+    "owner": {
+      "type": "string"
+    },
+    "period_days": {
+      "type": "number"
+    },
+    "repo": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "owner",
+    "repo",
+    "period_days",
+    "measured_from",
+    "measured_to",
+    "deployment_frequency",
+    "lead_time",
+    "change_failure_rate",
+    "mttr"
+  ],
+  "type": "object"
+}
    • Changedget_health_score1 field changed
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "report": {
+      "additionalProperties": false,
+      "properties": {
+        "breakdown": {
+          "additionalProperties": {
+            "additionalProperties": false,
+            "properties": {
+              "detail": {
+                "type": "string"
+              },
+              "score": {
+                "type": "number"
+              },
+              "weight": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "score",
+              "weight",
+              "detail"
+            ],
+            "type": "object"
+          },
+          "propertyNames": {
+            "type": "string"
+          },
+          "type": "object"
+        },
+        "checkedAt": {
+          "type": "string"
+        },
+        "grade": {
+          "type": "string"
+        },
+        "gradeMeaning": {
+          "type": "string"
+        },
+        "repo": {
+          "type": "string"
+        },
+        "score": {
+          "type": "number"
+        },
+        "suggestions": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "repo",
+        "score",
+        "grade",
+        "breakdown",
+        "suggestions",
+        "checkedAt",
+        "gradeMeaning"
+      ],
+      "type": "object"
+    },
+    "trend": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "direction": {
+              "type": "string"
+            },
+            "previousCheckedAt": {
+              "type": "string"
+            },
+            "previousGrade": {
+              "type": "string"
+            },
+            "previousScore": {
+              "type": "number"
+            },
+            "scoreDiff": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "previousScore",
+            "previousGrade",
+            "previousCheckedAt",
+            "scoreDiff",
+            "direction"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "report",
+    "trend"
+  ],
+  "type": "object"
+}
    • Changedget_repo_health1 field changed
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "archived": {
+      "type": "boolean"
+    },
+    "default_branch": {
+      "type": "string"
+    },
+    "description": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "forks_count": {
+      "type": "number"
+    },
+    "full_name": {
+      "type": "string"
+    },
+    "language": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "license": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "open_issues_count": {
+      "type": "number"
+    },
+    "pushed_at": {
+      "type": "string"
+    },
+    "stargazers_count": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "full_name",
+    "description",
+    "stargazers_count",
+    "open_issues_count",
+    "language",
+    "license",
+    "pushed_at",
+    "default_branch",
+    "archived",
+    "forks_count"
+  ],
+  "type": "object"
+}
  2. 8 tool updatesv1.1.4
    • Changedanalyze_code_scanning2 fields changed
      • changedInput schema / properties / owner / description
        Previous value: -"GitHub repository owner"New value: +"GitHub repository owner (e.g., 'modelcontextprotocol')"
      • changedInput schema / properties / repo / description
        Previous value: -"GitHub repository name"New value: +"GitHub repository name (e.g., 'sdk')"
    • Changedanalyze_dependencies2 fields changed
      • changedInput schema / properties / owner / description
        Previous value: -"GitHub repository owner"New value: +"GitHub repository owner (e.g., 'modelcontextprotocol')"
      • changedInput schema / properties / repo / description
        Previous value: -"GitHub repository name"New value: +"GitHub repository name (e.g., 'sdk')"
    • Changedcheck_ci_status2 fields changed
      • changedInput schema / properties / owner / description
        Previous value: -"GitHub repository owner"New value: +"GitHub repository owner (e.g., 'modelcontextprotocol')"
      • changedInput schema / properties / repo / description
        Previous value: -"GitHub repository name"New value: +"GitHub repository name (e.g., 'sdk')"
    • Addedcompare_repos
    • Addedget_dora_metrics
    • Changedget_health_score2 fields changed
      • changedInput schema / properties / owner / description
        Previous value: -"GitHub repository owner"New value: +"GitHub repository owner (e.g., 'modelcontextprotocol')"
      • changedInput schema / properties / repo / description
        Previous value: -"GitHub repository name"New value: +"GitHub repository name (e.g., 'sdk')"
    • Changedget_repo_health2 fields changed
      • changedInput schema / properties / owner / description
        Previous value: -"GitHub repository owner"New value: +"GitHub repository owner (e.g., 'modelcontextprotocol')"
      • changedInput schema / properties / repo / description
        Previous value: -"GitHub repository name"New value: +"GitHub repository name (e.g., 'sdk')"
    • Removedping
  3. 6 tool updatesv1.1.3
    • First observedanalyze_code_scanning
    • First observedanalyze_dependencies
    • First observedcheck_ci_status
    • First observedget_health_score
    • First observedget_repo_health
    • First observedping
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.7/5.0
Disambiguation5/5

Each tool targets a distinct concern: raw metadata, CI runs, dependency alerts, code scanning, composite health scoring, DORA metrics, and multi-repo comparison. The descriptions explicitly cross-reference when NOT to use each tool, making selection unambiguous.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern: get_, check_, analyze_, compare_. The naming is predictable and clearly conveys each tool's action and target.

Tool Count5/5

Seven tools form a well-scoped set for repository health analysis. Each tool covers a meaningful aspect of the domain without redundancy or bloat.

Completeness4/5

The tool set covers the core domain well: metadata, CI, security, dependencies, composite scoring, DORA metrics, and comparison. Minor gaps exist around direct PR/release inspection, but the included tools provide enough coverage for health assessment workflows.

Maintenance

ActivityNo data
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

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/alexbypa/github-projectpulse-mcp'

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