MokoStandards-Template-MCP

Template repository for creating MokoStandards-compliant Model Context Protocol (MCP) servers that expose REST APIs as AI assistant tools.

Use this template to scaffold a new MCP server for any API — Dolibarr, Joomla, GitHub, Stripe, or any REST service. Comes pre-configured with the standard file structure, CI/CD workflows, setup wizard, and example tools.

Table of Contents

• Quick Start
• What You Get
• Customization Guide
• File Structure
• Adding Tools
• License

Quick Start

1. Create from template

On Gitea, click "Use this template" to create a new repo, or clone and reinitialize:

git clone https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-Template-MCP.git my-api-mcp
cd my-api-mcp
rm -rf .git && git init

2. Search and replace placeholders

Replace these placeholders across all files:

Placeholder	Replace With	Example
{{PROJECT_NAME}}	Your project name (kebab-case)	dolibarr-api-mcp
{{DISPLAY_NAME}}	Human-readable API name	Dolibarr ERP/CRM
{{ENV_PREFIX}}	Env var prefix (UPPER_SNAKE)	DOLIBARR_API_MCP

# Linux/macOS
find . -type f -not -path './.git/*' -exec sed -i 's/{{PROJECT_NAME}}/my-api-mcp/g' {} +
find . -type f -not -path './.git/*' -exec sed -i 's/{{DISPLAY_NAME}}/My API/g' {} +
find . -type f -not -path './.git/*' -exec sed -i 's/{{ENV_PREFIX}}/MY_API_MCP/g' {} +

3. Customize the auth mechanism

Edit src/client.ts — update the headers in the constructor to match your API's authentication:

// Bearer token (GitHub, Joomla)
this.headers = { 'Authorization': `Bearer ${conn.apiKey}` };

// Custom header (Dolibarr)
this.headers = { 'DOLAPIKEY': conn.apiKey };

// Basic auth
this.headers = { 'Authorization': `Basic ${Buffer.from(user + ':' + pass).toString('base64')}` };

4. Update the API prefix

In src/client.ts, set API_PREFIX to your API's base path:

const API_PREFIX = '/api/v1';         // GitHub
const API_PREFIX = '/api/index.php';  // Dolibarr
const API_PREFIX = '/api/index.php/v1'; // Joomla

5. Add your tools

Replace the example tools in src/index.ts with your API endpoints. See Adding Tools.

6. Build and test

npm install
npm run build
npm run setup   # configure your first connection
npm start       # verify it starts

What You Get

Component	Description
src/index.ts	MCP server with example tools, shared helpers, and connection management
src/client.ts	HTTP client supporting GET/POST/PUT/PATCH/DELETE with TLS bypass
src/config.ts	Multi-connection config loader (~/.<project>.json)
src/types.ts	TypeScript interfaces for connection, config, and response
scripts/setup.mjs	Interactive setup wizard for adding API connections
config.example.json	Example multi-connection config
.gitea/workflows/	12 CI/CD workflows (auto-release, compliance, cleanup, etc.)
Makefile	Build automation (install, build, dev, clean, setup, start)
Standard files	.gitignore, .gitattributes, .gitmessage, tsconfig.json

Customization Guide

Config & Auth

File	What to Change
src/types.ts	Rename apiKey field if your API uses different auth (e.g. apiToken, username/password)
src/client.ts	Update API_PREFIX, auth headers, and HTTP methods (PUT vs PATCH)
src/config.ts	Update CONFIG_FILENAME and CONFIG_ENV_VAR
scripts/setup.mjs	Update AUTH_FIELD, AUTH_PROMPT, API_LABEL constants
config.example.json	Update field names to match your auth scheme

Setup Wizard

The setup wizard in scripts/setup.mjs has labeled constants at the top — update these to change the prompts, config filename, and auth field name.

File Structure

├── src/
│   ├── index.ts          # MCP server — register tools here
│   ├── client.ts         # HTTP client — customize auth & API prefix
│   ├── config.ts         # Config loader — customize filename & env var
│   └── types.ts          # TypeScript interfaces — customize auth fields
├── scripts/
│   └── setup.mjs         # Interactive setup wizard
├── .gitea/
│   ├── .mokostandards    # Platform: mcp-server
│   └── workflows/        # 12 CI/CD workflows
├── docs/                 # Documentation
├── package.json
├── tsconfig.json
├── config.example.json
├── Makefile
├── .gitignore
├── .gitattributes
└── .gitmessage

Adding Tools

Each tool follows this pattern:

server.tool(
    'prefix_resource_list',                    // snake_case name
    'List resources with optional filtering',  // description for AI
    {
        search: z.string().optional().describe('Search query'),
        status: z.enum(['active', 'archived']).optional().describe('Filter by status'),
        ...PaginationParams,
        ...ConnectionParam,
    },
    async ({ search, status, limit, page, connection }) => {
        const client = clientFor(connection);
        const params: Record<string, string> = { ...paginationQuery({ limit, page }) };
        if (search) params['search'] = search;
        if (status) params['status'] = status;
        return formatResponse(await client.get('/resources', params));
    },
);

Naming conventions

• List: prefix_resources_list (plural noun)
• Get: prefix_resource_get (singular)
• Create: prefix_resource_create
• Update: prefix_resource_update
• Delete: prefix_resource_delete
• Actions: prefix_resource_validate, prefix_resource_close, etc.

Organization

Group tools by resource type with section comments:

// ── Invoices ────────────────────────────────────────────────────────────
// ── Products ────────────────────────────────────────────────────────────
// ── Users ───────────────────────────────────────────────────────────────

Contributing

See CONTRIBUTING.md for guidelines.

License

GPL-3.0-or-later — see LICENSE.

Copyright © 2026 Moko Consulting hello@mokoconsulting.tech

Maintainers

@mokoconsulting-tech

Revision History

Date	Version	Author	Notes
2026-05-07	0.0.1	jmiller	Initial MCP server template