Template
docs: update README from wiki Home
This commit is contained in:
@@ -1,219 +1,55 @@
|
||||
<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
|
||||
# Template-MCP
|
||||
|
||||
This file is part of a Moko Consulting project.
|
||||
Template repository for creating MokoStandards-compliant MCP API servers
|
||||
|
||||
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)
|
||||
Template repository for creating MokoStandards-compliant MCP API servers
|
||||
|
||||
# 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 |
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| `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` |
|
||||
| **Language** | TypeScript |
|
||||
| **License** | GPL-3.0-or-later |
|
||||
| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP) |
|
||||
|
||||
## Customization Guide
|
||||
---
|
||||
|
||||
### Config & Auth
|
||||
## Guides
|
||||
|
||||
| File | What to Change |
|
||||
| Page | Description |
|
||||
|---|---|
|
||||
| `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 |
|
||||
| [INSTALLATION](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP/wiki/INSTALLATION) | - **Node.js** 20.0.0 or later |
|
||||
|
||||
### Setup Wizard
|
||||
## Reference
|
||||
|
||||
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.
|
||||
| Page | Description |
|
||||
|---|---|
|
||||
| [API](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP/wiki/API) | All tools accept an optional `connection` parameter to target a specific named connection. If omitte... |
|
||||
| [ARCHITECTURE](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP/wiki/ARCHITECTURE) | {{PROJECT_NAME}} is a Model Context Protocol (MCP) server that bridges AI assistants with a REST API... |
|
||||
|
||||
## 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
|
||||
```
|
||||
> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)
|
||||
|
||||
## 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.
|
||||
## Documentation
|
||||
|
||||
### Organization
|
||||
|
||||
Group tools by resource type with section comments:
|
||||
|
||||
```typescript
|
||||
// ── Invoices ────────────────────────────────────────────────────────────
|
||||
// ── Products ────────────────────────────────────────────────────────────
|
||||
// ── Users ───────────────────────────────────────────────────────────────
|
||||
```
|
||||
Full documentation is available on the [Wiki](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP/wiki).
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
||||
See the wiki for development guidelines and contribution instructions.
|
||||
|
||||
## License
|
||||
|
||||
GPL-3.0-or-later — see [LICENSE](LICENSE).
|
||||
This project is licensed under the GNU General Public License v3.0 or later -- see the [LICENSE](LICENSE) file.
|
||||
|
||||
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 |
|
||||
*[Moko Consulting](https://mokoconsulting.tech) -- [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*
|
||||
|
||||
Reference in New Issue
Block a user