@decocms/mesh 1.0.0-alpha.8 → 1.0.0-alpha.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/README.md +296 -0
- package/package.json +1 -1
package/dist/README.md
ADDED
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
<img alt="MCP Mesh" src="https://github.com/user-attachments/assets/d3e36c98-4609-46d3-b39f-7ee1c6d77432" />
|
|
2
|
+
|
|
3
|
+
<h1 align="center">MCP Mesh</h1>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<em>MCP-native · TypeScript-first · Deploy anywhere</em><br/><br/>
|
|
7
|
+
<b>One secure endpoint for every MCP server.</b>
|
|
8
|
+
</p>
|
|
9
|
+
|
|
10
|
+
<p align="center">
|
|
11
|
+
<a href="https://docs.deco.page/">📘 Docs</a> ·
|
|
12
|
+
<a href="https://decocms.com/discord">💬 Discord</a> ·
|
|
13
|
+
<a href="https://decocms.com/mesh">🌐 decocms.com/mesh</a>
|
|
14
|
+
</p>
|
|
15
|
+
|
|
16
|
+
> **TL;DR:**
|
|
17
|
+
> - Route all MCP traffic through a single governed endpoint
|
|
18
|
+
> - Enforce RBAC, policies, and audit trails at the control plane
|
|
19
|
+
> - Full observability with OpenTelemetry — traces, costs, errors
|
|
20
|
+
> - Self-host with Docker, Bun, or run locally
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## What is MCP Mesh?
|
|
25
|
+
|
|
26
|
+
**MCP Mesh** is an open-source control plane for MCP traffic. It sits between your MCP clients (Cursor, Claude, VS Code, custom agents) and your MCP servers, providing a unified layer for auth, policy, and observability.
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
┌─────────────────────────────────────────────────────────────────┐
|
|
30
|
+
│ MCP Clients │
|
|
31
|
+
│ Cursor · Claude · VS Code · Custom Agents │
|
|
32
|
+
└───────────────────────────┬─────────────────────────────────────┘
|
|
33
|
+
│
|
|
34
|
+
▼
|
|
35
|
+
┌─────────────────────────────────────────────────────────────────┐
|
|
36
|
+
│ MCP MESH │
|
|
37
|
+
│ Gateway · Policy Engine · Observability · Token Vault │
|
|
38
|
+
└───────────────────────────┬─────────────────────────────────────┘
|
|
39
|
+
│
|
|
40
|
+
▼
|
|
41
|
+
┌─────────────────────────────────────────────────────────────────┐
|
|
42
|
+
│ MCP Servers │
|
|
43
|
+
│ Salesforce · Slack · GitHub · Postgres · Your APIs │
|
|
44
|
+
└─────────────────────────────────────────────────────────────────┘
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Stop wiring every client to every MCP. Stop rebuilding auth for every agent.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Quick Start
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
# Clone and install
|
|
55
|
+
git clone https://github.com/decocms/mesh.git
|
|
56
|
+
cd mesh
|
|
57
|
+
bun install
|
|
58
|
+
|
|
59
|
+
# Run locally
|
|
60
|
+
bun run dev
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
→ runs at [http://localhost:4000](http://localhost:4000) (client) + API server
|
|
64
|
+
|
|
65
|
+
Or use `npm create deco` to scaffold a new project with the CLI.
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Core Capabilities
|
|
70
|
+
|
|
71
|
+
| Layer | Description |
|
|
72
|
+
|-------|-------------|
|
|
73
|
+
| 🧩 **MeshContext** | Unified runtime interface providing auth, storage, observability, and policy control |
|
|
74
|
+
| ⚙️ **defineTool()** | Declarative API for typed, auditable, observable MCP tools |
|
|
75
|
+
| 🧱 **AccessControl** | Fine-grained RBAC via Better Auth — OAuth 2.1 + API keys per workspace/project |
|
|
76
|
+
| 📊 **OpenTelemetry** | Full tracing and metrics for tools, workflows, and UI interactions |
|
|
77
|
+
| 💾 **Storage Adapters** | Kysely ORM → SQLite / Postgres, easily swapped |
|
|
78
|
+
| ☁️ **Proxy Layer** | Secure bridge to remote MCP servers with token vault + OAuth |
|
|
79
|
+
| 🧰 **Virtual MCPs** | Compose and expose governed toolsets as new MCP servers |
|
|
80
|
+
| 📬 **Event Bus** | Pub/sub between connections with scheduled/cron delivery and at-least-once guarantees |
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## Define Tools
|
|
85
|
+
|
|
86
|
+
Tools are first-class citizens. Type-safe, audited, observable, and callable via MCP.
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
import { z } from "zod";
|
|
90
|
+
import { defineTool } from "~/core/define-tool";
|
|
91
|
+
|
|
92
|
+
export const CONNECTION_CREATE = defineTool({
|
|
93
|
+
name: "CONNECTION_CREATE",
|
|
94
|
+
description: "Create a new MCP connection",
|
|
95
|
+
inputSchema: z.object({
|
|
96
|
+
name: z.string(),
|
|
97
|
+
connection: z.object({
|
|
98
|
+
type: z.enum(["HTTP", "SSE", "WebSocket"]),
|
|
99
|
+
url: z.string().url(),
|
|
100
|
+
token: z.string().optional(),
|
|
101
|
+
}),
|
|
102
|
+
}),
|
|
103
|
+
outputSchema: z.object({
|
|
104
|
+
id: z.string(),
|
|
105
|
+
scope: z.enum(["workspace", "project"]),
|
|
106
|
+
}),
|
|
107
|
+
handler: async (input, ctx) => {
|
|
108
|
+
await ctx.access.check();
|
|
109
|
+
const conn = await ctx.storage.connections.create({
|
|
110
|
+
projectId: ctx.project?.id ?? null,
|
|
111
|
+
...input,
|
|
112
|
+
createdById: ctx.auth.user!.id,
|
|
113
|
+
});
|
|
114
|
+
return { id: conn.id, scope: conn.projectId ? "project" : "workspace" };
|
|
115
|
+
},
|
|
116
|
+
});
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Every tool call gets: type validation, access control checks, audit logging, and OpenTelemetry traces — automatically.
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## Project Structure
|
|
124
|
+
|
|
125
|
+
```
|
|
126
|
+
├── apps/
|
|
127
|
+
│ ├── mesh/ # Full-stack MCP Mesh (Hono API + Vite/React)
|
|
128
|
+
│ │ ├── src/
|
|
129
|
+
│ │ │ ├── api/ # Hono HTTP + MCP proxy routes
|
|
130
|
+
│ │ │ ├── auth/ # Better Auth (OAuth + API keys)
|
|
131
|
+
│ │ │ ├── core/ # MeshContext, AccessControl, defineTool
|
|
132
|
+
│ │ │ ├── tools/ # Built-in MCP management tools
|
|
133
|
+
│ │ │ ├── storage/ # Kysely DB adapters
|
|
134
|
+
│ │ │ ├── event-bus/ # Pub/sub event delivery system
|
|
135
|
+
│ │ │ ├── encryption/ # Token vault & credential management
|
|
136
|
+
│ │ │ ├── observability/ # OpenTelemetry tracing & metrics
|
|
137
|
+
│ │ │ └── web/ # React 19 admin UI
|
|
138
|
+
│ │ └── migrations/ # Kysely database migrations
|
|
139
|
+
│ └── docs/ # Astro documentation site
|
|
140
|
+
│
|
|
141
|
+
└── packages/
|
|
142
|
+
├── bindings/ # Core MCP bindings and connection abstractions
|
|
143
|
+
├── runtime/ # MCP proxy, OAuth, and runtime utilities
|
|
144
|
+
├── ui/ # Shared React components (shadcn-based)
|
|
145
|
+
├── cli/ # CLI tooling (deco commands)
|
|
146
|
+
├── create-deco/ # Project scaffolding (npm create deco)
|
|
147
|
+
└── vite-plugin-deco/ # Vite plugin for Deco projects
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Development
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
# Install dependencies
|
|
156
|
+
bun install
|
|
157
|
+
|
|
158
|
+
# Run dev server (client + API)
|
|
159
|
+
bun run dev
|
|
160
|
+
|
|
161
|
+
# Run tests
|
|
162
|
+
bun test
|
|
163
|
+
|
|
164
|
+
# Type check
|
|
165
|
+
bun run check
|
|
166
|
+
|
|
167
|
+
# Lint
|
|
168
|
+
bun run lint
|
|
169
|
+
|
|
170
|
+
# Format
|
|
171
|
+
bun run fmt
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### Mesh-specific commands (from `apps/mesh/`)
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
bun run dev:client # Vite dev server (port 4000)
|
|
178
|
+
bun run dev:server # Hono server with hot reload
|
|
179
|
+
bun run migrate # Run database migrations
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## Deploy Anywhere
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
# Docker Compose (SQLite)
|
|
188
|
+
docker compose -f deploy/docker-compose.yml up
|
|
189
|
+
|
|
190
|
+
# Docker Compose (PostgreSQL)
|
|
191
|
+
docker compose -f deploy/docker-compose.postgres.yml up
|
|
192
|
+
|
|
193
|
+
# Self-host with Bun
|
|
194
|
+
bun run build:client && bun run build:server
|
|
195
|
+
bun run start
|
|
196
|
+
|
|
197
|
+
# Kubernetes
|
|
198
|
+
kubectl apply -f k8s/
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
Runs on any infrastructure — Docker, Kubernetes, AWS, GCP, or local Bun/Node runtimes. No vendor lock-in.
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
## Tech Stack
|
|
206
|
+
|
|
207
|
+
| Layer | Tech |
|
|
208
|
+
|-------|------|
|
|
209
|
+
| Runtime | Bun / Node |
|
|
210
|
+
| Language | TypeScript + Zod |
|
|
211
|
+
| Framework | Hono (API) + Vite + React 19 |
|
|
212
|
+
| Database | Kysely → SQLite / PostgreSQL |
|
|
213
|
+
| Auth | Better Auth (OAuth 2.1 + API keys) |
|
|
214
|
+
| Observability | OpenTelemetry |
|
|
215
|
+
| UI | React 19 + Tailwind v4 + shadcn |
|
|
216
|
+
| Protocol | Model Context Protocol (MCP) |
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
## Comparison
|
|
221
|
+
|
|
222
|
+
### vs Mastra
|
|
223
|
+
|
|
224
|
+
| | **Mastra** | **MCP Mesh** |
|
|
225
|
+
|---|---|---|
|
|
226
|
+
| Category | TypeScript agent/workflow framework | MCP control plane + runtime |
|
|
227
|
+
| Focus | Build agent primitives, RAG, workflows | Route, govern, and observe MCP traffic |
|
|
228
|
+
| Protocol | Model/provider-agnostic | MCP-native |
|
|
229
|
+
| Auth | Framework-level | OAuth 2.1 + RBAC + API keys |
|
|
230
|
+
| Observability | Tracing/evals at framework level | End-to-end OpenTelemetry |
|
|
231
|
+
| Deployment | Node.js / serverless | Docker / Bun / Self-host |
|
|
232
|
+
|
|
233
|
+
### vs Metorial
|
|
234
|
+
|
|
235
|
+
| | **Metorial** | **MCP Mesh** |
|
|
236
|
+
|---|---|---|
|
|
237
|
+
| Focus | Connect AI to APIs | Control plane for MCP traffic |
|
|
238
|
+
| Language | Go + TS | 100% TypeScript |
|
|
239
|
+
| Infra | Docker | Docker / Bun / Self-host |
|
|
240
|
+
| Auth | API keys | OAuth 2.1 + RBAC + spend caps |
|
|
241
|
+
| Observability | Dashboard | Full OpenTelemetry |
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## Roadmap
|
|
246
|
+
|
|
247
|
+
- [ ] Multi-tenant admin dashboard
|
|
248
|
+
- [ ] Runtime strategies (smart routing, code execution)
|
|
249
|
+
- [ ] MCP bindings (swap providers without rewrites)
|
|
250
|
+
- [ ] Edge debugger / live tracing
|
|
251
|
+
- [ ] Cost analytics and spend caps
|
|
252
|
+
- [ ] MCP Store — discover and install pre-built MCP apps
|
|
253
|
+
|
|
254
|
+
---
|
|
255
|
+
|
|
256
|
+
## Part of decoCMS
|
|
257
|
+
|
|
258
|
+
MCP Mesh is the core infrastructure layer of [decoCMS](https://decocms.com).
|
|
259
|
+
|
|
260
|
+
| Layer | What it does |
|
|
261
|
+
|-------|--------------|
|
|
262
|
+
| **MCP Mesh** | Connect, govern, and observe MCP traffic |
|
|
263
|
+
| **MCP Studio** | Build MCP capabilities (no-code admin + SDK) |
|
|
264
|
+
| **MCP Store** | Discover and install pre-built MCP apps |
|
|
265
|
+
|
|
266
|
+
---
|
|
267
|
+
|
|
268
|
+
## License
|
|
269
|
+
|
|
270
|
+
MCP Mesh ships with a **Sustainable Use License (SUL)**. See [LICENSE.md](./LICENSE.md).
|
|
271
|
+
|
|
272
|
+
- ✅ Free to self-host for internal use
|
|
273
|
+
- ✅ Free for client projects (agencies, consultancies, SIs)
|
|
274
|
+
- ⚠️ Commercial license required for SaaS or revenue-generating production systems
|
|
275
|
+
|
|
276
|
+
Questions? [contact@decocms.com](mailto:contact@decocms.com)
|
|
277
|
+
|
|
278
|
+
---
|
|
279
|
+
|
|
280
|
+
## Contributing
|
|
281
|
+
|
|
282
|
+
We welcome contributions! Run the following before submitting a PR:
|
|
283
|
+
|
|
284
|
+
```bash
|
|
285
|
+
bun run fmt # Format code
|
|
286
|
+
bun run lint # Check linting
|
|
287
|
+
bun test # Run tests
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
See `AGENTS.md` for detailed coding guidelines and conventions.
|
|
291
|
+
|
|
292
|
+
---
|
|
293
|
+
|
|
294
|
+
<div align="center">
|
|
295
|
+
<sub>Made with ❤️ by the <a href="https://decocms.com">deco</a> community</sub>
|
|
296
|
+
</div>
|