It helps you build modular, maintainable MCP servers using clean structure and naming conventions based on primarily on CGUDL (Create, Get, Update, Delete, List), but you can use ACTION type naming conventions.

Features

Scaffold full MCP HexLayer projects
Add integrations, tools, services, and schemas
Works with uv
Built with Typer

Installation

To install Perch, use pip:

pip install perch-py

For more details, visit the Perch-Py PyPI page.

Usage

Perch provides commands to initialize new projects, create new projects in separate directories, and add various components (integrations, tools, services, schemas) to an existing project.

Initialize Project in Current Directory (`perch init`)

Initializes a Perch project in the current working directory.

perch init

With an optional integration:

perch init --integration github

To initialize a project where the -mcp-server suffix is not enforced on the project name:

perch init --normal # Note: Not Recommended

Create New Project (`perch create`)

Creates a new Perch project in a new directory. By default, if no --normal flag is used, the project name for an MCP server will be strictly suffixed with -mcp-server (e.g., my-server becomes my-server-mcp-server).

perch create my-mcp-server

With an optional integration:

perch create my-mcp-server --integration github

To create a project where the -mcp-server suffix is not enforced on the project name:

perch create my-normal-project --normal # Note: Not Recommended

After Project Initialization/Creation

After perch init or perch create, navigate into your project directory and activate the virtual environment:

cd my-mcp-server # or my-normal-project
uv venv activate
python main.py

Add Commands (`perch add`)

The perch add command is used to add various components to an existing Perch project.

Add Integration (`perch add integration`)

Adds a new integration by creating its directory structure and a client.py file.

perch add integration github

Creates:

integrations/github/
interfaces/tools/github/
interfaces/resources/github/
schemas/github/
services/github/
integrations/github/client.py

And the content of integrations/github/client.py:

# integrations/github/client.py
class GithubClient:
    def __init__(self):
        pass

    def connect(self):
        # Implement connection logic here
        print(f"Connecting to {self.__class__.__name__}...")
        pass

Add Tool (`perch add tool`)

Adds a new tool file for a given integration and entity.

perch add tool github user

Creates:

# interfaces/tools/github/user.py
from core.data.tool import ToolResponse
from pydantic import Field
from schemas.github.user import UserInputSchema, UserResponseSchema
from services.github.user import create_user

def create_user_tool(
    sample1: str = Field(..., description="The sample1 of the user."),
    sample2: str = Field(..., description="The sample2 of the user.")
) -> T

Categories

Current Category: clean-architecture

dotnet-mcp-hero

perch-py