Scaffold and Phase 0-1
This commit is contained in:
@@ -1,47 +1,111 @@
|
||||
# Drop-In Agent Instruction Suite
|
||||
# totalmcp
|
||||
|
||||
This repository is a portable markdown instruction pack for coding agents.
|
||||
Unified MCP gateway for Jason's ALPHA stack. One Dockerized server, hot-reloadable plugin architecture, three agent clients (Claude Code, Codex, Antigravity) all connecting to one stable endpoint.
|
||||
|
||||
Copy these files into another repository to give the agent:
|
||||
- a root `AGENTS.md` entrypoint,
|
||||
- a central skill index,
|
||||
- category hubs for routing,
|
||||
- specialized skill files for common software, docs, UX, marketing, and ideation tasks.
|
||||
- **Port:** `8811`
|
||||
- **Static IP:** `10.2.0.35` (Unraid `br0`)
|
||||
- **Registry:** `git.alwisp.com/jason/totalmcp`
|
||||
- **Spec:** see [`PLAN.md`](PLAN.md) for the full architecture and phased roadmap
|
||||
- **Service inventory:** see [`SERVICES.md`](SERVICES.md) for the catalog this gateway plugs into
|
||||
|
||||
## Structure
|
||||
## Quick Start (local dev)
|
||||
|
||||
- `AGENTS.md` - base instructions and routing rules
|
||||
- `DEPLOYMENT-PROFILE.md` - agent-readable prefilled deployment defaults
|
||||
- `INSTALL.md` - copy and customization guide for other repositories
|
||||
- `PROJECT-PROFILE-WORKBOOK.md` - one-time questionnaire for staging defaults
|
||||
- `SKILLS.md` - canonical skill index
|
||||
- `ROUTING-EXAMPLES.md` - representative prompt-to-skill routing examples
|
||||
- `hubs/` - category-level routing guides
|
||||
- `skills/` - specialized reusable skill files
|
||||
```bash
|
||||
cp .env.example .env # then fill in tokens
|
||||
npm install
|
||||
npm run prisma:generate
|
||||
npm run dev # starts tsx watch on src/server.ts
|
||||
```
|
||||
|
||||
## Design Goals
|
||||
Verify:
|
||||
|
||||
- Plain markdown only
|
||||
- Cross-agent portability
|
||||
- Implementation-first defaults
|
||||
- On-demand skill loading instead of loading everything every session
|
||||
- Context-efficient routing for large skill libraries
|
||||
- Prefilled deployment defaults without per-install questioning
|
||||
- Repo-local instructions take precedence over this bundle
|
||||
```bash
|
||||
curl http://localhost:8811/health
|
||||
# → { "status": "ok", "version": "0.1.0", "plugins": 0, "enabled": [] }
|
||||
```
|
||||
|
||||
## Intended Workflow
|
||||
## Build & run
|
||||
|
||||
1. The agent reads `AGENTS.md`.
|
||||
2. The agent reads `DEPLOYMENT-PROFILE.md` when it is filled in.
|
||||
3. The agent checks `SKILLS.md`.
|
||||
4. The agent opens only the relevant hub and skill files for the task.
|
||||
5. The agent combines multiple skills when the task spans several domains.
|
||||
```bash
|
||||
npm run build # tsc → dist/
|
||||
npm start # node dist/server.js
|
||||
```
|
||||
|
||||
## Core Categories
|
||||
## Docker
|
||||
|
||||
- Software development
|
||||
- Debugging
|
||||
- Documentation
|
||||
- UI/UX
|
||||
- Marketing
|
||||
- Brainstorming
|
||||
```bash
|
||||
docker compose up --build -d
|
||||
docker compose logs -f totalmcp
|
||||
```
|
||||
|
||||
## Endpoints
|
||||
|
||||
| Method | Path | Auth | Purpose |
|
||||
|--------|-------------|----------|--------------------------------------|
|
||||
| GET | `/health` | none | Liveness — used by Unraid HEALTHCHECK |
|
||||
| GET | `/plugins` | bearer | Loaded plugin list + tool counts |
|
||||
| POST | `/mcp` | bearer | Streamable HTTP — primary MCP transport |
|
||||
| GET | `/mcp` | bearer | Streamable HTTP server-sent stream |
|
||||
| DELETE | `/mcp` | bearer | Streamable HTTP session close |
|
||||
| GET | `/sse` | bearer | Legacy SSE (Antigravity) |
|
||||
| POST | `/message` | bearer | Legacy SSE message channel |
|
||||
|
||||
## Authoring a plugin
|
||||
|
||||
Drop a directory under `src/plugins/<name>/index.ts` and `export default` an `MCPPlugin`. Tool names must be fully-qualified (`<service>_<action>`) and unique across all loaded plugins.
|
||||
|
||||
```typescript
|
||||
import { z } from "zod";
|
||||
import type { MCPPlugin } from "../../types/plugin.js";
|
||||
|
||||
const plugin: MCPPlugin = {
|
||||
name: "example",
|
||||
version: "0.1.0",
|
||||
description: "Example plugin",
|
||||
minGatewayVersion: "0.1.0",
|
||||
tools: [
|
||||
{
|
||||
name: "example_ping",
|
||||
description: "Returns pong",
|
||||
inputSchema: z.object({}),
|
||||
handler: async () => ({ result: "pong" }),
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
export default plugin;
|
||||
```
|
||||
|
||||
Then add `example` to `ENABLED_PLUGINS` in `.env`. In dev (`npm run dev`), chokidar picks up the change in ~2s. In prod, push to Gitea and let CI rebuild the image.
|
||||
|
||||
Reference implementations live at [`src/plugins/gitea/`](src/plugins/gitea/index.ts) and [`src/plugins/unraid/`](src/plugins/unraid/index.ts).
|
||||
|
||||
## Repo layout
|
||||
|
||||
```
|
||||
totalmcp/
|
||||
├── src/
|
||||
│ ├── server.ts # Express bootstrap
|
||||
│ ├── registry.ts # Plugin loader + hot-reload
|
||||
│ ├── config.ts # Zod env validation
|
||||
│ ├── logger.ts # Structured JSON logger
|
||||
│ ├── types/plugin.ts # MCPPlugin interface
|
||||
│ ├── auth/bearer.ts # Per-agent token middleware
|
||||
│ ├── mcp/build.ts # MCP server wiring
|
||||
│ ├── transport/
|
||||
│ │ ├── streamable.ts # Streamable HTTP transport
|
||||
│ │ └── sse.ts # Legacy SSE transport
|
||||
│ ├── util/http.ts # Shared HTTP helper (timeouts, JSON, errors)
|
||||
│ └── plugins/
|
||||
│ ├── gitea/index.ts # Phase 1 — Gitea REST API
|
||||
│ └── unraid/index.ts # Phase 1 — Unraid GraphQL API
|
||||
├── prisma/schema.prisma # Event log schema
|
||||
├── Dockerfile
|
||||
├── docker-compose.yml
|
||||
├── .env.example
|
||||
└── package.json
|
||||
```
|
||||
|
||||
## Roadmap
|
||||
|
||||
See [`PLAN.md`](PLAN.md) for the full phased plan. Phase 0 (this scaffold) is intentionally minimal — empty registry, both transports respond, Docker image builds, container boots clean.
|
||||
|
||||
Reference in New Issue
Block a user