Template
Jonathan Miller
91b78f8da1
Template repository for creating MokoStandards-compliant MCP servers.
Includes 4-file src/ structure (index, client, config, types), setup
wizard, example tools, 12 CI/CD workflows, full docs, and {{placeholder}}
tokens for search-and-replace customization.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
220 lines
7.8 KiB
Markdown
220 lines
7.8 KiB
Markdown
<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
|
|
|
|
This file is part of a Moko Consulting project.
|
|
|
|
SPDX-LICENSE-IDENTIFIER: GPL-3.0-or-later
|
|
|
|
# FILE INFORMATION
|
|
DEFGROUP: MokoStandards-Template-MCP.Documentation
|
|
INGROUP: MokoStandards-Template-MCP
|
|
REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-Template-MCP
|
|
VERSION: 01.00.00
|
|
PATH: ./README.md
|
|
BRIEF: Template repository for MCP API servers
|
|
-->
|
|
|
|
|
|
[](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 (`~/.<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:
|
|
|
|
```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<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:
|
|
|
|
```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 <hello@mokoconsulting.tech>
|
|
|
|
## 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 |
|