docs: rewrite README with detailed project documentation

2026-05-10 19:29:31 +00:00
parent db77114fde
commit baaf203ddd
1 changed files with 56 additions and 31 deletions
@@ -1,46 +1,71 @@
 # Template-MCP

-Template repository for creating MokoStandards-compliant MCP API servers
+![Language](https://img.shields.io/badge/language-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) ![Platform](https://img.shields.io/badge/platform-Node.js%20%7C%20MCP-339933?style=flat-square&logo=node.js&logoColor=white) ![Wiki](https://img.shields.io/badge/wiki-Template--MCP-blue?style=flat-square)

-![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)
+Template repository for creating MokoStandards-compliant Model Context Protocol (MCP) API servers. Provides the scaffolding, configuration patterns, and architecture conventions used by all Moko Consulting MCP servers, enabling AI assistants like Claude to interact with REST APIs through a standardized tool interface.

+## Features

-Template repository for creating MokoStandards-compliant MCP API servers
+- **MCP server scaffolding** -- pre-configured TypeScript project structure with entry point, tool registration, and stdio transport ready to go
+- **Multi-connection support** -- built-in `config.json` pattern for managing multiple named API connections with a default fallback; all tools accept an optional `connection` parameter
+- **REST API bridge architecture** -- standardized pattern for bridging any REST API as MCP tools, with typed request/response handling
+- **TypeScript-first** -- full TypeScript setup with `tsconfig.json`, strict mode, and ES module output
+- **Build tooling** -- Makefile with `build`, `dev`, `clean`, and `lint` targets; npm scripts for compilation and development
+- **MokoStandards compliant** -- follows all Moko Consulting governance conventions: file headers, commit messages, `.gitattributes`, `.gitmessage`, PR/issue templates
+- **Example configuration** -- `config.example.json` demonstrates the connection configuration schema
+- **Documentation templates** -- wiki pages for API reference, architecture overview, and installation pre-generated

-| Field | Value |
+## Installation
+
+1. Create a new repository from this template (or clone directly):
+   ```bash
+   git clone https://git.mokoconsulting.tech/MokoConsulting/Template-MCP.git my-mcp-server
+   cd my-mcp-server
+   ```
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+3. Copy and configure the connection file:
+   ```bash
+   cp config.example.json config.json
+   # Edit config.json with your API credentials
+   ```
+4. Build the project:
+   ```bash
+   npm run build
+   ```
+5. Run the server:
+   ```bash
+   node build/index.js
+   ```
+
+## Configuration
+
+| Path | Purpose |
 |---|---|
-| **Language** | TypeScript |
-| **License** | GPL-3.0-or-later |
-| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP) |
+| `src/` | TypeScript source files (server entry, tool definitions, API client) |
+| `config.example.json` | Example multi-connection configuration schema |
+| `config.json` | Local connection configuration (gitignored) |
+| `package.json` | npm dependencies and scripts |
+| `tsconfig.json` | TypeScript compiler configuration |
+| `scripts/` | Build and development utility scripts |
+| `docs/` | Developer documentation |
+| `Makefile` | Build, dev, clean, and lint targets |

---
+## Requirements

-## Guides
-
-| Page | Description |
-|---|---|
-| [INSTALLATION](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP/wiki/INSTALLATION) | - **Node.js** 20.0.0 or later |
-
-## Reference
-
-| 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... |
-
---
-
-> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)
-
---
-
-
-
---
+- Node.js 20.0.0 or later
+- npm 9+
+- TypeScript 5+ (installed via npm)

 ## Documentation

-Full documentation is available on the [Wiki](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP/wiki).
+Full documentation is available on the [Wiki](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP/wiki), including:
+
+- [API](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP/wiki/API) -- tool reference and connection parameter documentation
+- [ARCHITECTURE](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP/wiki/ARCHITECTURE) -- MCP server design and REST API bridge pattern
+- [INSTALLATION](https://git.mokoconsulting.tech/MokoConsulting/Template-MCP/wiki/INSTALLATION) -- setup prerequisites and configuration guide

 ## Contributing