[](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-Template-MCP/releases/tag/v00) [](LICENSE) [](https://nodejs.org) # MokoStandards-Template-MCP [](https://github.com/RichardLitt/standard-readme) 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](#quick-start) - [What You Get](#what-you-get) - [Customization Guide](#customization-guide) - [File Structure](#file-structure) - [Adding Tools](#adding-tools) - [License](#license) ## Quick Start ### 1. Create from template On Gitea, click **"Use this template"** to create a new repo, or clone and reinitialize: ```sh 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` | ```sh # 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: ```typescript // 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: ```typescript 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](#adding-tools). ### 6. Build and test ```sh 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 (`~/..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: ```typescript 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 = { ...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: ```typescript // ── Invoices ──────────────────────────────────────────────────────────── // ── Products ──────────────────────────────────────────────────────────── // ── Users ─────────────────────────────────────────────────────────────── ``` ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## License GPL-3.0-or-later — see [LICENSE](LICENSE). Copyright © 2026 Moko Consulting ## Maintainers [@mokoconsulting-tech](https://git.mokoconsulting.tech/MokoConsulting) ## Revision History | Date | Version | Author | Notes | | --- | --- | --- | --- | | 2026-05-07 | 0.0.1 | jmiller | Initial MCP server template |