projectpulse-mcp

get_health_score

Idempotent

Calculate a 0-100 health score and A-F grade for any GitHub repository, combining CI status, security, community, and maintenance data with actionable improvement tips.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`repo`	Yes	GitHub repository name (e.g., 'sdk')
`owner`	Yes	GitHub repository owner (e.g., 'modelcontextprotocol')

Output Schema

TableJSON Schema

Name	Required	Description	Default
`trend`	Yes
`report`	Yes
`badgeSnippet`	Yes
`recommendations`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.6.14Sep 8, 2026

addedOutput schema / properties / badgeSnippet
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / recommendations

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "category": {
+        "type": "string"
+      },
+      "impact": {
+        "type": "string"
+      },
+      "message": {
+        "type": "string"
+      },
+      "priority": {
+        "enum": [
+          "high",
+          "medium",
+          "low"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "category",
+      "priority",
+      "message",
+      "impact"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "report",
-  "trend"
-]New value: +[
+  "report",
+  "trend",
+  "recommendations",
+  "badgeSnippet"
+]

Changed1 schema field changedv1.1.7Sep 5, 2026

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"
+}

Changed2 schema fields changedv1.1.4Sep 5, 2026

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')"

First observedv1.1.3Aug 30, 2026

TDQS

A4.6/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'), clarifies it is 'Read-only against GitHub API', and covers auth requirements and rate limits. This goes well beyond the sparse annotations and gives the agent a clear model of the tool's behavior and impact.

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 longer than average but well-structured with labeled sections for side effects, data sources, auth, rate limits, return shape, and usage guidance. It front-loads the core purpose and organizes supplementary details, making it easy to scan without being padded.

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 analytic tool, the description covers return shape, side effects, auth, rate limits, data sources, and explicit usage boundaries with sibling alternatives. The provided context is sufficient for an agent to decide when and how to 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?

Both parameters (owner and repo) are fully described in the schema with concrete examples, providing 100% schema coverage. The description text itself does not add additional semantic depth beyond what the schema already supplies, so it meets the baseline but does not exceed it.

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 a 0-100 health score and A-F grade for a GitHub repository.' It clearly identifies the tool's purpose and distinguishes it from siblings by positioning it for 'deep analytical grading and overall repository health assessment' rather than quick metadata checks.

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 for deep analytical grading') and when not to, naming specific sibling alternatives such as get_repo_health, check_ci_status, analyze_code_scanning, and get_dora_metrics. 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.

Deploy Server