MokoConsulting/Template-MCP

Template

Fork 0

Table of Contents

Contributing Guidelines

Branch Workflow
Commit Messages
Pull Request Process

Requirements
PR Template

Tool Design Standards

Naming Conventions
Parameter Design
Response Format

TypeScript Standards
File Organization
Related

← Home

Contributing Guidelines

How to contribute to MCP servers built from the Template-MCP template.

Branch Workflow

Branch	Purpose
`main`	Stable production release
`dev`	Integration and testing
`feature`	Active feature development (merges to dev)
`version`	Version preparation and staging
`beta`	Beta testing channel
`alpha`	Alpha testing channel
`feature/*`	Named feature branches (merge to dev)
`fix/*`	Bug fix branches (merge to dev)
`hotfix/*`	Urgent fixes (merge to dev or main)
`rc/*`	Release candidates (merge to main)

git checkout dev && git pull
git checkout -b feature/add-resource-tools

Commit Messages

Follow Conventional Commits:

type(scope): description

Type	When
`feat`	New MCP tool or capability
`fix`	Bug fix in tool logic or client
`refactor`	Code restructuring
`chore`	Build, config, dependency changes
`docs`	Documentation updates
`test`	Adding or updating tests

Examples:

feat(tools): add resource_create and resource_update tools
fix(client): handle 204 No Content responses
refactor(config): extract connection resolver to helper
chore(deps): update @modelcontextprotocol/sdk to 1.5.0

Pull Request Process

Requirements

Title follows commit message format
All CI checks pass
TypeScript compiles without errors (npm run build)
ESLint passes (npm run lint)
New tools follow naming conventions
New tools have descriptive .describe() on all parameters

PR Template

## What changed
[Brief description]

## New tools added
- `tool_name` -- description

## Testing
- [ ] `npm run build` succeeds
- [ ] `npm run lint` passes
- [ ] Tested tool calls via Claude Code
- [ ] Tested with multiple connections
- [ ] Error cases handled gracefully

Tool Design Standards

Naming Conventions

Pattern	Example
List resources	`resource_list`
Get single	`resource_get`
Create	`resource_create`
Update	`resource_update`
Delete	`resource_delete`
Custom action	`resource_action_name`

All tool names use snake_case.

Parameter Design

server.tool(
  'resource_list',
  'List resources with optional filtering',  // Clear, concise description
  {
    search: z.string().optional().describe('Filter by name or description'),
    status: z.enum(['active', 'inactive']).optional().describe('Filter by status'),
    ...PaginationParams,
    ...ConnectionParam,
  },
  async (params) => {
    // Implementation
  }
);

Rule	Detail
Every parameter gets `.describe()`	Tells Claude how to use it
Use `.optional()` liberally	Only require truly mandatory params
Use Zod enums for constrained values	Prevents invalid input
Spread `ConnectionParam`	Every tool gets connection selection
Spread `PaginationParams`	List tools get pagination

Response Format

Always use formatResponse() for consistent output:

const result = await client.get('/api/resource/' + id);
return formatResponse(result);

For custom error messages:

if (result.statusCode === 404) {
  return { content: [{ type: 'text', text: `Resource ${id} not found` }] };
}

TypeScript Standards

Rule	Standard
Strict mode	`"strict": true` in tsconfig
ES modules	`import/export`, not `require`
Type safety	No `any` types without justification
Interfaces	Define in `src/types.ts`
Async/await	Prefer over raw Promises

File Organization

File	Content
`src/index.ts`	Tool registration and handlers
`src/client.ts`	HTTP client (`ApiClient` class)
`src/config.ts`	Configuration loader
`src/types.ts`	TypeScript interfaces
`scripts/setup.mjs`	Interactive setup wizard

Add new tools in src/index.ts. If a tool needs complex logic, extract helper functions but keep tool registration in index.ts.

Development -- tool implementation guide
Testing -- test procedures
Architecture -- design decisions

Repo: Template-MCP · MokoStandards

Field	Value
Minimum Version	04.07.00
Platform	mcp-server
Applies To	MCP server repositories

Revision	Date	Author	Description
1.0	2026-05-19	Moko Consulting	Initial version