reddit-research-mcp: Instructions file for Claude Code

Reddit Research MCP Server - Development Guide

Project Overview

This is a Python MCP server built with FastMCP that provides Reddit research capabilities. It's published to:

• PyPI: reddit-research-mcp
• MCP Registry: io.github.king-of-the-grackles/reddit-research-mcp

Key Files

File	Purpose
pyproject.toml	Python package configuration, version, dependencies
server.json	MCP Registry configuration
README.md	Must contain mcp-name: line for registry validation
.github/workflows/publish-mcp.yml	CI/CD for PyPI + MCP Registry publishing

Releasing New Versions

Automated Release Process

1. Update versions in both files (must match):

   • pyproject.toml: version = "X.Y.Z"
   • server.json: "version": "X.Y.Z" (in both places)

2. Commit and tag:

   git add pyproject.toml server.json
   git commit -m "chore: bump version to X.Y.Z"
   git tag vX.Y.Z
   git push origin main --tags
   

3. GitHub Actions automatically:

   • Builds the Python package
   • Publishes to PyPI
   • Updates server.json version from tag
   • Authenticates to MCP Registry via GitHub OIDC
   • Publishes to MCP Registry

Required GitHub Secrets

• PYPI_TOKEN: PyPI API token scoped to reddit-research-mcp package

MCP Registry Requirements

server.json Schema

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
  "name": "io.github.king-of-the-grackles/reddit-research-mcp",
  "description": "...",
  "repository": {
    "url": "https://github.com/king-of-the-grackles/reddit-research-mcp",
    "source": "github"
  },
  "version": "1.0.1",
  "packages": [
    {
      "registryType": "pypi",
      "identifier": "reddit-research-mcp",
      "version": "1.0.1",
      "runtimeHint": "uvx",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

README.md Requirement

The README must contain this line (typically at the very top):