atabey-mcp 0.0.17 → 0.0.18
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/README.md +351 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,351 @@
|
|
|
1
|
+
# [GOV] Atabey MCP — MCP Server for AI Governance & Multi-Agent Orchestration
|
|
2
|
+
|
|
3
|
+
[](https://github.com/ysf-bkr/atabey)
|
|
4
|
+
[](https://www.npmjs.com/package/atabey-mcp)
|
|
5
|
+
[](https://www.gnu.org/licenses/agpl-3.0)
|
|
6
|
+
[](https://modelcontextprotocol.io)
|
|
7
|
+
[](https://github.com/ysf-bkr/atabey)
|
|
8
|
+
|
|
9
|
+
**Atabey MCP** is the MCP (Model Context Protocol) server component of the Agent Atabey framework. It provides 32 MCP tools, a 13-layer governance pipeline, vector memory, risk engine, loop detection, FinOps budget management, auto-rollback, prompt injection protection, and a real-time WebSocket dashboard.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## 📋 Package Overview
|
|
14
|
+
|
|
15
|
+
| Capability | Description |
|
|
16
|
+
|-----------|-------------|
|
|
17
|
+
| **MCP Tools** | 32 tools across 8 categories: file system, search, messaging, governance, memory, quality, network, orchestration |
|
|
18
|
+
| **Governance Pipeline** | 13-layer pre/post execution validation: PII masking, risk gate, discipline, loop detection, FinOps, license scan, auto-rollback, injection protection |
|
|
19
|
+
| **Memory** | Vector memory with TF-IDF/OpenAI embeddings, project memory, knowledge base |
|
|
20
|
+
| **Dashboard** | Real-time WebSocket dashboard with 12 live modules |
|
|
21
|
+
| **Auth** | Bearer token authentication for HTTP/SSE mode |
|
|
22
|
+
| **Multi-Transport** | Stdio (per-developer) + HTTP/SSE (team server) |
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 🚀 Installation
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npm install -g atabey-mcp
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Quick Start
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
# Start MCP server (stdio mode)
|
|
36
|
+
atabey-mcp
|
|
37
|
+
|
|
38
|
+
# Start with dashboard (HTTP/SSE mode)
|
|
39
|
+
MCP_TRANSPORT=http MCP_PORT=5858 atabey-mcp
|
|
40
|
+
# Dashboard: http://localhost:5858
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 🛠️ 32 MCP Tools
|
|
46
|
+
|
|
47
|
+
### File System (6)
|
|
48
|
+
| Tool | Description |
|
|
49
|
+
|------|-------------|
|
|
50
|
+
| `read_file` | Read file content with line range support |
|
|
51
|
+
| `view_file` | Alias for read_file |
|
|
52
|
+
| `write_file` | Write content to file, auto-create directories |
|
|
53
|
+
| `replace_text` | Surgical string replacement |
|
|
54
|
+
| `batch_surgical_edit` | Multi-file batch surgical edits |
|
|
55
|
+
| `patch_file` | Line-range based safe file update |
|
|
56
|
+
|
|
57
|
+
### Search & Exploration (4)
|
|
58
|
+
| Tool | Description |
|
|
59
|
+
|------|-------------|
|
|
60
|
+
| `list_dir` | List directory contents |
|
|
61
|
+
| `grep_search` | Recursive regex search |
|
|
62
|
+
| `get_project_map` | Tree-view project structure |
|
|
63
|
+
| `get_project_gaps` | TODO/FIXME/empty function scan |
|
|
64
|
+
|
|
65
|
+
### Framework & System (10)
|
|
66
|
+
| Tool | Description |
|
|
67
|
+
|------|-------------|
|
|
68
|
+
| `run_shell_command` | Restricted shell execution |
|
|
69
|
+
| `run_tests` | Execute test suites |
|
|
70
|
+
| `get_system_health` | CPU/RAM metrics |
|
|
71
|
+
| `check_active_ports` | Active port scan |
|
|
72
|
+
| `get_framework_status` | Phase, trace, agent states |
|
|
73
|
+
| `read_project_memory` | Read PROJECT_MEMORY.md |
|
|
74
|
+
| `get_memory_insights` | Memory summary |
|
|
75
|
+
| `update_project_memory` | Update memory |
|
|
76
|
+
| `orchestrate_loop` | Process Hermes messages |
|
|
77
|
+
| `submit_plan` | Submit DAG plan |
|
|
78
|
+
|
|
79
|
+
### Control Plane (3)
|
|
80
|
+
| Tool | Description |
|
|
81
|
+
|------|-------------|
|
|
82
|
+
| `acquire_lock` | Lock shared resource |
|
|
83
|
+
| `release_lock` | Release lock |
|
|
84
|
+
| `register_agent` | Register agent instance |
|
|
85
|
+
|
|
86
|
+
### Memory & Knowledge (4)
|
|
87
|
+
| Tool | Description |
|
|
88
|
+
|------|-------------|
|
|
89
|
+
| `store_knowledge` | Store to vector memory |
|
|
90
|
+
| `search_knowledge` | Search vector memory |
|
|
91
|
+
| `delete_knowledge` | Delete knowledge entry |
|
|
92
|
+
| `update_contract_hash` | Update contract hash |
|
|
93
|
+
|
|
94
|
+
### Messaging & Human (3)
|
|
95
|
+
| Tool | Description |
|
|
96
|
+
|------|-------------|
|
|
97
|
+
| `send_agent_message` | Hermes agent-to-agent message |
|
|
98
|
+
| `log_agent_action` | Log to framework |
|
|
99
|
+
| `ask_human` | Ask developer a question |
|
|
100
|
+
|
|
101
|
+
### Compliance & Quality (4)
|
|
102
|
+
| Tool | Description |
|
|
103
|
+
|------|-------------|
|
|
104
|
+
| `mask_pii` | KVKK/GDPR PII masking API |
|
|
105
|
+
| `analyze_code_quality` | TypeScript quality analysis |
|
|
106
|
+
| `check_architecture_compliance` | Layer boundary check |
|
|
107
|
+
| `check_lint` | ESLint execution |
|
|
108
|
+
|
|
109
|
+
### Operations (3)
|
|
110
|
+
| Tool | Description |
|
|
111
|
+
|------|-------------|
|
|
112
|
+
| `approve_operation` | In-chat risk gate approval |
|
|
113
|
+
| `compress_files` | ZIP/TAR/GZIP compression |
|
|
114
|
+
| `decompress_files` | Archive extraction |
|
|
115
|
+
| `http_proxy_request` | Secure HTTP proxy |
|
|
116
|
+
| `audit_dependencies` | Unused package audit |
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## 🔐 13-Layer Governance Pipeline
|
|
121
|
+
|
|
122
|
+
Every MCP tool call passes through this pipeline:
|
|
123
|
+
|
|
124
|
+
```
|
|
125
|
+
CallToolRequest
|
|
126
|
+
↓
|
|
127
|
+
1. [VALIDATION] Zod schema validation
|
|
128
|
+
2. [GOVERNANCE] validateArgsAgainstRules()
|
|
129
|
+
3. [DISCIPLINE] enforceDiscipline()
|
|
130
|
+
4. [LOOP DETECTION] recordAndCheck() + cooldown
|
|
131
|
+
5. [FINOPS] budgetManager.recordUsage()
|
|
132
|
+
6. [LICENSE] validateLicenseCompliance()
|
|
133
|
+
7. [AUTO-ROLLBACK] prepareWrite() snapshot
|
|
134
|
+
8. [HUMAN-IN-LOOP] RiskEngine.assessTaskRisk() + checkRiskGate()
|
|
135
|
+
9. [PII MASKING] maskToolArgs() → mask before handler
|
|
136
|
+
10. [EXECUTION] Tool handler runs
|
|
137
|
+
11. [POST-VALIDATION] scanFileForViolations() → rollback if needed
|
|
138
|
+
12. [INJECTION PROTECTION] sanitizeResponse()
|
|
139
|
+
13. [PII MASKING] maskToolResult() → mask before returning to AI
|
|
140
|
+
↓
|
|
141
|
+
Return governed result
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Pipeline Details
|
|
145
|
+
|
|
146
|
+
| Layer | Module | Description |
|
|
147
|
+
|-------|--------|-------------|
|
|
148
|
+
| **Validation** | `zod-to-mcp.ts` | All tool inputs validated against Zod schemas |
|
|
149
|
+
| **Governance** | `rules-engine.ts` | Pre-execution argument validation against governance rules |
|
|
150
|
+
| **Discipline** | `discipline.ts` | AI behavior enforcement: rate limiting, file size limits, tool blacklist |
|
|
151
|
+
| **Loop Detection** | `loop-detector.ts` | Blocks >10 consecutive same-tool calls, cooldown mechanism |
|
|
152
|
+
| **FinOps** | `finops.ts` | Per-agent token/cost tracking, monthly budgets, auto-shutdown |
|
|
153
|
+
| **License** | `license-scanner.ts` | Copyleft license detection in write operations |
|
|
154
|
+
| **Auto-Rollback** | `auto-rollback.ts` | Pre-write snapshot, post-write governance scan, automatic restore |
|
|
155
|
+
| **Human-in-Loop** | `human-in-loop.ts` | Risk score ≥ 60 requires approval via `approve_operation` tool |
|
|
156
|
+
| **PII Masking** | `pii.ts` | 20+ PII patterns masked before/after handler execution |
|
|
157
|
+
| **Injection Protection** | `prompt-injection.ts` | OWASP LLM01 compliant: role-playing, override, jailbreak detection |
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## 🧠 Memory & Knowledge
|
|
162
|
+
|
|
163
|
+
### Vector Memory
|
|
164
|
+
```typescript
|
|
165
|
+
store_knowledge(content, category, tags) → generateEmbedding() → VectorStore.addEntry()
|
|
166
|
+
search_knowledge(query) → generateEmbedding() → VectorStore.search() → cosine similarity sort
|
|
167
|
+
delete_knowledge(id) → SQLite DELETE
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
- **Technology**: SQLite + Float32Array vectors
|
|
171
|
+
- **Embedding**: OpenAI text-embedding-3-small (1536-dim) or TF-IDF fallback (384-dim)
|
|
172
|
+
- **Categories**: ARCHITECTURE, DECISION, CODE_SNIPPET, RULE, TASK_HISTORY
|
|
173
|
+
|
|
174
|
+
### Knowledge Base
|
|
175
|
+
- REST API: `/api/knowledge` (GET list), `/api/knowledge/view?file=X` (GET), `/api/knowledge/update` (POST)
|
|
176
|
+
- SQLite persisted with upsert support
|
|
177
|
+
- PII masked on all responses
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## 📊 Dashboard
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
MCP_TRANSPORT=http MCP_PORT=5858 atabey-mcp
|
|
185
|
+
# Opens at http://localhost:5858
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
| Module | Description | Update |
|
|
189
|
+
|--------|-------------|--------|
|
|
190
|
+
| 🤖 **Agent Monitor** | AI agent status + tasks | WS (5s) |
|
|
191
|
+
| 📨 **Hermes Stats** | Message queue statistics | WS (5s) |
|
|
192
|
+
| 💬 **Hermes Messages** | Message queue viewer + filter | WS (5s) |
|
|
193
|
+
| 🔐 **Approval Center** | Human-in-the-Loop approvals | WS |
|
|
194
|
+
| 📋 **Task Planner** | Task DAG + progress | REST (5s) |
|
|
195
|
+
| 📝 **Agent Logs** | Execution logs | WS (5s) |
|
|
196
|
+
| ⚠️ **Error Tracker** | Lint/compliance/security errors | WS |
|
|
197
|
+
| 🧠 **Memory Insights** | Vector memory search | REST |
|
|
198
|
+
| 🛡️ **Compliance** | Quality gate violations | REST (15s) |
|
|
199
|
+
| ✅ **Quality Panel** | Code quality analysis | REST |
|
|
200
|
+
| 🔌 **Adapters** | Adapter-skill mapping | REST |
|
|
201
|
+
| 🔒 **GDPR / KVKK** | PII masking, erasure, audit trail | REST |
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
## 🔌 MCP Transport Modes
|
|
206
|
+
|
|
207
|
+
### Stdio Mode (Default - Per Developer)
|
|
208
|
+
```bash
|
|
209
|
+
atabey-mcp
|
|
210
|
+
# Connects via stdin/stdout JSON-RPC
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
### HTTP/SSE Mode (Team Server)
|
|
214
|
+
```bash
|
|
215
|
+
MCP_TRANSPORT=http MCP_PORT=5858 atabey-mcp
|
|
216
|
+
```
|
|
217
|
+
```json
|
|
218
|
+
// Client mcp.json:
|
|
219
|
+
{
|
|
220
|
+
"mcpServers": {
|
|
221
|
+
"atabey": {
|
|
222
|
+
"url": "http://192.168.1.100:5858/sse"
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### Authentication (HTTP/SSE Mode)
|
|
229
|
+
```bash
|
|
230
|
+
export MCP_AUTH_TOKEN="your-secret-token"
|
|
231
|
+
export MCP_AUTH_USERS="alice:key1,bob:key2"
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## 🔒 Security Features
|
|
237
|
+
|
|
238
|
+
### PII Masking (KVKK/GDPR)
|
|
239
|
+
| Pattern | Example | Masked |
|
|
240
|
+
|---------|---------|--------|
|
|
241
|
+
| Email | `user@example.com` | `***@***` |
|
|
242
|
+
| Phone | `+90 555 123 45 67` | `***-***-****` |
|
|
243
|
+
| TC ID | `12345678901` | `***********` |
|
|
244
|
+
| API Key | `sk-abc...xyz` | `***-REDACTED-***` |
|
|
245
|
+
| JWT Token | `eyJ...eyJ...` | `***-JWT-REDACTED-***` |
|
|
246
|
+
| IP Address | `192.168.1.1` | `***.***.***.***` |
|
|
247
|
+
| Credit Card | `4111 1111 1111 1111` | `****-****-****-****` |
|
|
248
|
+
| IBAN | `TR33...1326` | `****-IBAN-REDACTED-****` |
|
|
249
|
+
|
|
250
|
+
### AI Discipline Engine
|
|
251
|
+
- **Rate Limiting**: Max 60 calls/minute per agent
|
|
252
|
+
- **File Size Limits**: Prevents >1MB files
|
|
253
|
+
- **Loop Detection**: Blocks >10 consecutive same-tool calls
|
|
254
|
+
- **Cooldown**: Automatic when limits exceeded
|
|
255
|
+
- **Injection Protection**: OWASP LLM01 compliant
|
|
256
|
+
|
|
257
|
+
### Token Economy (FinOps)
|
|
258
|
+
- Per-agent token/cost tracking
|
|
259
|
+
- Monthly budgets via `ATABEY_BUDGET_MONTHLY`
|
|
260
|
+
- Per-agent budgets via `ATABEY_BUDGET_AGENT_MAX`
|
|
261
|
+
- 50/80/90/100% alert thresholds
|
|
262
|
+
- Auto-shutdown when budget exceeded
|
|
263
|
+
|
|
264
|
+
---
|
|
265
|
+
|
|
266
|
+
## 🏗️ Architecture
|
|
267
|
+
|
|
268
|
+
```
|
|
269
|
+
src/
|
|
270
|
+
├── mcp/
|
|
271
|
+
│ ├── index.ts # MCP server entry (stdio + HTTP/SSE)
|
|
272
|
+
│ ├── constants.ts # MCP constants
|
|
273
|
+
│ ├── declarations.d.ts # Type declarations
|
|
274
|
+
│ ├── resources/ # MCP resource handlers
|
|
275
|
+
│ ├── tools/
|
|
276
|
+
│ │ ├── definitions.ts # 32 tool definitions
|
|
277
|
+
│ │ ├── schemas.ts # Zod schemas for all tools
|
|
278
|
+
│ │ ├── types.ts # Tool type definitions
|
|
279
|
+
│ │ ├── index.ts # Tool handler registry
|
|
280
|
+
│ │ ├── compliance/ # mask_pii
|
|
281
|
+
│ │ ├── control_plane/ # locking, registry
|
|
282
|
+
│ │ ├── file_system/ # read, write, replace, patch, batch, compress
|
|
283
|
+
│ │ ├── framework/ # status, orchestrate, tests, plan, contract, memory
|
|
284
|
+
│ │ ├── memory/ # store, search, delete, insights
|
|
285
|
+
│ │ ├── messaging/ # send, log, ask, approve
|
|
286
|
+
│ │ ├── network/ # http_proxy
|
|
287
|
+
│ │ ├── observability/ # health, ports
|
|
288
|
+
│ │ ├── quality/ # analyze, architecture, lint
|
|
289
|
+
│ │ ├── search/ # grep, map, gaps, list
|
|
290
|
+
│ │ └── shell/ # run_command
|
|
291
|
+
│ └── utils/
|
|
292
|
+
│ ├── auth.ts # Bearer token authentication
|
|
293
|
+
│ ├── auto-rollback.ts # Pre-write snapshot + post-write validation
|
|
294
|
+
│ ├── cli.ts # CLI utility functions
|
|
295
|
+
│ ├── client-config.ts # MCP client configuration
|
|
296
|
+
│ ├── compliance.ts # Compliance checking
|
|
297
|
+
│ ├── context-optimizer.ts # Token budget optimization
|
|
298
|
+
│ ├── discipline.ts # AI behavior enforcement
|
|
299
|
+
│ ├── errors.ts # Error handling
|
|
300
|
+
│ ├── finops.ts # Token/cost tracking
|
|
301
|
+
│ ├── fs.ts # File system utilities
|
|
302
|
+
│ ├── human-in-loop.ts # Risk gate approval flow
|
|
303
|
+
│ ├── license-scanner.ts # License compliance
|
|
304
|
+
│ ├── loop-detector.ts # Infinite loop detection
|
|
305
|
+
│ ├── memory.ts # Framework directory resolution
|
|
306
|
+
│ ├── metrics.ts # Usage metrics
|
|
307
|
+
│ ├── permissions.ts # Permission checking
|
|
308
|
+
│ ├── prompt-injection.ts # OWASP LLM01 protection
|
|
309
|
+
│ ├── quality.ts # Code quality analysis
|
|
310
|
+
│ ├── rules-engine.ts # Governance rules
|
|
311
|
+
│ ├── security.ts # Security utilities
|
|
312
|
+
│ ├── silent-router.ts # Semantic agent routing
|
|
313
|
+
│ ├── storage.ts # SQLite storage
|
|
314
|
+
│ ├── telemetry-streamer.ts # Telemetry
|
|
315
|
+
│ ├── types.ts # Type definitions
|
|
316
|
+
│ ├── web-config.ts # Web configuration
|
|
317
|
+
│ ├── workspace.ts # Workspace utilities
|
|
318
|
+
│ └── zod-to-mcp.ts # Zod → MCP schema converter
|
|
319
|
+
└── shared/
|
|
320
|
+
├── audit.ts # Structured audit log
|
|
321
|
+
├── constants.ts # Shared constants
|
|
322
|
+
├── errors.ts # Error types
|
|
323
|
+
├── fs.ts # File system utilities
|
|
324
|
+
├── lock.ts # Distributed locking
|
|
325
|
+
├── logger.ts # Structured logging
|
|
326
|
+
├── pii.ts # PII masking (20+ patterns)
|
|
327
|
+
├── retention.ts # Data retention
|
|
328
|
+
├── storage.ts # SQLite storage engine
|
|
329
|
+
├── string.ts # String utilities
|
|
330
|
+
└── types.ts # Branded types
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
---
|
|
334
|
+
|
|
335
|
+
## 📦 Dependencies
|
|
336
|
+
|
|
337
|
+
- **atabey**: Core engine for agent definitions and orchestration
|
|
338
|
+
- **@modelcontextprotocol/sdk**: MCP protocol implementation
|
|
339
|
+
- **better-sqlite3**: SQLite database
|
|
340
|
+
- **zod**: Runtime schema validation
|
|
341
|
+
- **chalk**: Terminal UI
|
|
342
|
+
- **ws**: WebSocket for dashboard
|
|
343
|
+
- **js-yaml**: YAML parsing for agent definitions
|
|
344
|
+
|
|
345
|
+
---
|
|
346
|
+
|
|
347
|
+
## License
|
|
348
|
+
|
|
349
|
+
AGPL-3.0 — Yusuf BEKAR
|
|
350
|
+
|
|
351
|
+
*Developer: **Yusuf BEKAR** — "Order from Chaos"*
|