mcp-starter

A GitHub template for building MCP servers — pre-configured for A+ schema quality.

---

What this gives you

• A+ schema quality from day one. Tool descriptions that are clear, typed, and efficient. Every parameter has a type and description. No token waste.
• CI grading on every push. The included GitHub Actions workflow runs agent-friend on every commit. PRs that drop the schema quality fail the check.
• Pre-commit hook. Catches schema issues before they reach CI.
• Example tools. Three working tools (search_items, get_item, create_item) demonstrating MCP schema best practices.

Why this matters

The 200 most-used MCP servers average 78 tokens/tool. The top 4 most-starred ones all grade F.

Token costs are real: at $15/1M tokens, 200 tools at 152 tokens each = $0.46/session in schema overhead before the agent does anything. Bad schemas compound — every session, forever.

Starting with a good schema is free. Retrofitting it later isn't.

Getting started

1. Click Use this template → Create new repository
2. Replace my-mcp-server with your server name in pyproject.toml
3. Edit server.py — replace the example tools with your actual tools
4. Push — the GitHub Actions workflow grades your schema automatically

Schema quality checklist

The example tools demonstrate:

• Every tool has a clear, imperative description (not "This tool helps you...")
• Every parameter has a type declaration
• Every parameter has a description explaining its purpose
• String parameters have length constraints where appropriate
• Integer parameters have min/max constraints where appropriate
• Optional parameters have defaults documented
• No prompt injection patterns in descriptions
• No markdown formatting in descriptions

Run the grader locally:

pip install agent-friend

# Regenerate schema.json from server.py after changing tools:
python3 export_schema.py

# Grade the schema:
agent-friend grade schema.json

schema.json is a generated file — regenerate it whenever you change tools in server.py, then commit the updated schema.json. The pre-commit hook validates it on every commit.

Project structure

├── server.py                    # MCP server — edit this
├── schema.json                  # Generated tool definitions for grading — regenerate with export_schema.py
├── export_schema.py             # Exports server.py tools to schema.json
├── pyproject.toml               # Package config
├── .pre-commit-config.yaml      # Pre-commit hooks (agent-friend grades schema.json on commit)
└── .github/
    └── workflows/
        └── grade.yml            # CI: regenerates schema.json and grades it

Resources

• agent-friend — the grader/fixer
• MCP Leaderboard — 201 servers graded A+ to F
• MCP Report Card — grade any server online