From db77114fde853b96036dbb66b0a1e8f3b771846f Mon Sep 17 00:00:00 2001 From: Jonathan Miller Date: Sun, 10 May 2026 18:39:16 +0000 Subject: [PATCH] docs: update README from wiki Home --- README.md | 218 +++++++----------------------------------------------- 1 file changed, 27 insertions(+), 191 deletions(-) diff --git a/README.md b/README.md index 595d75c..0e6a3f6 100644 --- a/README.md +++ b/README.md @@ -1,219 +1,55 @@ - +![Language](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white) ![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green?style=flat-square) ![Wiki](https://img.shields.io/badge/wiki-Template-MCP-blue?style=flat-square) -[![Version](https://img.shields.io/badge/version-01.00.00-blue.svg?logo=v&logoColor=white)](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-Template-MCP/releases/tag/v00) -[![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green.svg?logo=gnu&logoColor=white)](LICENSE) -[![Node](https://img.shields.io/badge/Node.js-20%2B-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org) +Template repository for creating MokoStandards-compliant MCP API servers -# MokoStandards-Template-MCP - -[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](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 (`~/..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 = { ...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 +--- -## 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)*