Skip to main content

​
Overview

Nectr’s MCP server exposes 4 tools that external agents can invoke to query review data, contributor statistics, PR verdicts, and repository health metrics. All tools are async functions that return plain Python dicts/lists and implement graceful error handling.

​
get_recent_reviews

Get recent PR reviews for a repository with verdicts and summaries.
​
repo
string
required
Full repository name, e.g., owner/repo
​
limit
integer
default:10
Maximum number of reviews to return (capped at 50)

​
Returns

List of review objects:
​
id
integer
required
Workflow run ID from the database
​
repo
string
required
Full repository name
​
pr_number
integer
GitHub pull request number
​
verdict
string
required
AI verdict: APPROVED, CHANGES_REQUESTED, COMMENT, or UNKNOWN
​
summary
string
required
Plain-English review summary
​
created_at
string
ISO 8601 timestamp when the review was created
​
status
string
required
Workflow status: completed, failed, processing, or pending

​
Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_recent_reviews",
    "arguments": {
      "repo": "acme/backend",
      "limit": 5
    }
  }
}

​
Implementation

Queries the WorkflowRun table filtered by workflow_type = 'pr_review', ordered by created_at DESC: 
app/mcp/server.py:106

​
get_contributor_stats

Get top contributors for a repository with PR-touch counts from the Neo4j knowledge graph.
​
repo
string
required
Full repository name, e.g., owner/repo

​
Returns

List of contributor objects:
​
login
string
required
GitHub username
​
pr_count
integer
required
Number of PRs that touched files in this repository

​
Example

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_contributor_stats",
    "arguments": {
      "repo": "acme/backend"
    }
  }
}

​
Implementation

Queries Neo4j using the graph_builder.get_file_experts() service: 
app/mcp/server.py:125
app/services/graph_builder.py (get_file_experts)
Returns an empty list if Neo4j is not configured or the query fails. This ensures graceful degradation.

​
get_pr_verdict

Get Nectr’s AI verdict for a specific pull request.
​
repo
string
required
Full repository name, e.g., owner/repo
​
pr_number
integer
required
GitHub PR number

​
Returns

Single verdict object or error:
​
repo
string
required
Full repository name
​
pr_number
integer
required
GitHub pull request number
​
verdict
string
AI verdict: APPROVED, CHANGES_REQUESTED, COMMENT, or UNKNOWN
​
summary
string
Plain-English review summary
​
created_at
string
ISO 8601 timestamp when the review was created
​
error
string
Error message if the review is not found or the query fails

​
Example

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_pr_verdict",
    "arguments": {
      "repo": "acme/backend",
      "pr_number": 123
    }
  }
}

​
Implementation

Queries the WorkflowRun table for the most recent 100 pr_review workflows, then filters by PR number: 
app/mcp/server.py:138
The search is limited to the last 100 reviews for performance. If the PR is older, it may not be found.

​
get_repo_health

Get overall repository health metrics and a 0–100 health score.
​
repo
string
required
Full repository name, e.g., owner/repo

​
Returns

Health metrics object:
​
repo
string
required
Full repository name
​
review_coverage_pct
integer
required
Percentage of PRs with AI reviews (0–100)
​
avg_merge_time_hours
number
Average time from PR open to merge in hours. Currently null (requires merge-event tracking).
​
open_prs_indexed
integer
required
Number of completed PR reviews in the database
​
health_score
integer
required
Overall health score (0–100), derived from review activity
​
note
string
Informational note about missing metrics
​
error
string
Error message if the query fails

​
Example

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_repo_health",
    "arguments": {
      "repo": "acme/backend"
    }
  }
}

​
Health Score Calculation

The health score is derived from the number of completed reviews: 
health_score = min(100, int((reviewed_count / 20) * 100))
  • 0 reviews → 0% health
  • 10 reviews → 50% health
  • 20+ reviews → 100% health

​
Implementation

app/mcp/server.py:192
avg_merge_time_hours is currently null because Nectr does not track merge events yet. This is a planned feature.

​
Error Handling

All tools implement defensive error handling:
  1. Try to query the database or Neo4j graph
  2. On exception, log a warning and return:
    • Empty list [] for list-returning tools
    • {"error": "message"} for object-returning tools
  3. Never crash — external agents always get a valid JSON-RPC response

​
Example Error

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": []
  }
}

​
Timeouts

MCP tool calls do not have explicit timeouts. However:
  • Database queries use SQLAlchemy’s async engine with connection pooling
  • Neo4j queries have a default 30-second timeout
  • FastMCP handles request cancellation if the client disconnects

​
Rate Limiting

The MCP server does not implement rate limiting. For production deployments with untrusted clients, add rate limiting middleware at the FastAPI level.

​
Source Code

All tools are implemented in: 
app/mcp/server.py:106-237
Helper functions:
  • _query_db_reviews() — Database query for reviews (line 33)
  • _query_contributor_stats() — Neo4j query for contributors (line 83)

Build docs developers (and LLMs) love

Get started for freeTalk to us