MCP Tools

Callable functions exposed by Nectr MCP server

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

Request

{
  "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

Request

{
  "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

Request

{
  "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

Request

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