🐺 Initial commit - Lupul Augmentat MCP Server
- MCP server cu stdio transport pentru performanță maximă
- Tool-uri pentru file operations, HTTP requests, system commands
- Suport NATS pentru comunicare inter-module
- Configurare nginx cu API key auth și SSL
- Arhitectură modulară și extensibilă
🤖 Generated with Claude Code
This commit is contained in:
Claude (Lupul Augmentat)
115
docs/ARHITECTURA.md
Normal file
115
docs/ARHITECTURA.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# 🏗️ ARHITECTURA MCP SERVER
|
||||
|
||||
## ⚡ REGULI DE AUR (NICIODATA NU ȘTERG!)
|
||||
|
||||
1. **NICI UN TASK NU SE CONSIDERĂ ÎNDEPLINIT** până nu se îndeplinesc criteriile de acceptanță definite
|
||||
2. **NU ÎNCEPEM UN TASK** până nu definim criteriile de acceptanță
|
||||
3. **UN SINGUR TASK ÎN LUCRU** - restul în standby
|
||||
4. **DOCUMENTAȚIA RĂMÂNE ÎN ARBORE** - toate fișierele conectate
|
||||
5. **NU LUCREZI NICIODATĂ LA ALTCEVA** decât ți s-a spus explicit
|
||||
6. **NICIODATA NU HARDCODEZ VARIABILE!**
|
||||
7. **NICIODATA NU ADAUGAM SETARI FAILOVERS** - Dacă ceva nu e bine, vrem să știm imediat
|
||||
8. **Salvez date relevante taskului curent** în DEBUG_CURRENT_TASK.md
|
||||
9. **Salvez întotdeauna ce am modificat** pentru rollback dacă e nevoie
|
||||
10. **Creez criterii de acceptanță** înainte de a testa/finaliza
|
||||
11. **Când task-uri depind de API changes** → salvez în TASK_IN_STANDBY.md
|
||||
|
||||
[← Înapoi la CLAUDE.md](../CLAUDE.md)
|
||||
|
||||
## 🎯 OVERVIEW
|
||||
|
||||
MCP Server pentru augmentarea capabilităților Claude cu tool-uri custom.
|
||||
|
||||
**Configurație:**
|
||||
- **Port:** 19017
|
||||
- **Bind:** 127.0.0.1 (doar local)
|
||||
- **Protocol:** MCP (Model Context Protocol)
|
||||
- **Access extern:** nginx proxy → mcp.runningwolf.com
|
||||
|
||||
## 📦 COMPONENTE PRINCIPALE
|
||||
|
||||
### 1. Core Server
|
||||
```typescript
|
||||
// src/server.ts
|
||||
class MCPServer {
|
||||
port: number = 19017
|
||||
host: string = '127.0.0.1'
|
||||
|
||||
// Tool registry
|
||||
// Transport layer
|
||||
// Request handler
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Tool System
|
||||
```typescript
|
||||
// src/tools/
|
||||
interface Tool {
|
||||
name: string
|
||||
description: string
|
||||
inputSchema: JSONSchema
|
||||
handler: ToolHandler
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Transport Layer
|
||||
- **stdio** - pentru development local
|
||||
- **HTTP/WebSocket** - pentru producție
|
||||
- **Authentication** - pentru securitate
|
||||
|
||||
## 🔧 TOOL-URI PLANIFICATE
|
||||
|
||||
1. **File Operations**
|
||||
- Read/Write fișiere locale
|
||||
- Watch pentru modificări
|
||||
- Batch operations
|
||||
|
||||
2. **System Integration**
|
||||
- Execute comenzi
|
||||
- Monitor procese
|
||||
- Environment variables
|
||||
|
||||
3. **Data Processing**
|
||||
- JSON/CSV parsing
|
||||
- Data transformări
|
||||
- Aggregări
|
||||
|
||||
4. **External APIs**
|
||||
- HTTP requests
|
||||
- WebSocket connections
|
||||
- API key management
|
||||
|
||||
## 🔒 SECURITATE
|
||||
|
||||
1. **Bind doar local** - 127.0.0.1:19017
|
||||
2. **Auth tokens** pentru access
|
||||
3. **Rate limiting** per tool
|
||||
4. **Audit logs** pentru toate operațiile
|
||||
|
||||
## 📁 STRUCTURA PROIECT
|
||||
|
||||
```
|
||||
/Projects/mcp/
|
||||
├── src/
|
||||
│ ├── server.ts # Entry point
|
||||
│ ├── config.ts # Configurări (NO HARDCODE!)
|
||||
│ ├── tools/ # Tool implementations
|
||||
│ │ ├── index.ts
|
||||
│ │ ├── file.ts
|
||||
│ │ └── system.ts
|
||||
│ └── transport/ # Transport layers
|
||||
│ ├── stdio.ts
|
||||
│ └── http.ts
|
||||
├── tests/ # Unit & integration tests
|
||||
├── package.json
|
||||
└── tsconfig.json
|
||||
```
|
||||
|
||||
## 🔗 LEGĂTURI
|
||||
|
||||
- [Setup Instructions](./SETUP.md)
|
||||
- [Available Tools](./TOOLS.md)
|
||||
- [Task History](./TASKS.md)
|
||||
|
||||
---
|
||||
*Actualizat: 25 Iulie 2025*
|
||||
152
docs/SETUP.md
Normal file
152
docs/SETUP.md
Normal file
@@ -0,0 +1,152 @@
|
||||
# 🚀 SETUP MCP SERVER
|
||||
|
||||
## ⚡ REGULI DE AUR (NICIODATA NU ȘTERG!)
|
||||
|
||||
1. **NICI UN TASK NU SE CONSIDERĂ ÎNDEPLINIT** până nu se îndeplinesc criteriile de acceptanță definite
|
||||
2. **NU ÎNCEPEM UN TASK** până nu definim criteriile de acceptanță
|
||||
3. **UN SINGUR TASK ÎN LUCRU** - restul în standby
|
||||
4. **DOCUMENTAȚIA RĂMÂNE ÎN ARBORE** - toate fișierele conectate
|
||||
5. **NU LUCREZI NICIODATĂ LA ALTCEVA** decât ți s-a spus explicit
|
||||
6. **NICIODATA NU HARDCODEZ VARIABILE!**
|
||||
7. **NICIODATA NU ADAUGAM SETARI FAILOVERS** - Dacă ceva nu e bine, vrem să știm imediat
|
||||
8. **Salvez date relevante taskului curent** în DEBUG_CURRENT_TASK.md
|
||||
9. **Salvez întotdeauna ce am modificat** pentru rollback dacă e nevoie
|
||||
10. **Creez criterii de acceptanță** înainte de a testa/finaliza
|
||||
11. **Când task-uri depind de API changes** → salvez în TASK_IN_STANDBY.md
|
||||
|
||||
[← Înapoi la CLAUDE.md](../CLAUDE.md)
|
||||
|
||||
## 📋 PREREQUISITES
|
||||
|
||||
- Node.js 18+
|
||||
- npm sau yarn
|
||||
- TypeScript 5+
|
||||
|
||||
## 🔧 INSTALARE
|
||||
|
||||
### 1. Clone și Setup Initial
|
||||
|
||||
```bash
|
||||
cd /Projects/mcp
|
||||
npm install
|
||||
```
|
||||
|
||||
### 2. Configurare Environment
|
||||
|
||||
```bash
|
||||
# .env (NEVER COMMIT!)
|
||||
MCP_HOST=127.0.0.1
|
||||
MCP_PORT=19017
|
||||
MCP_LOG_LEVEL=info
|
||||
```
|
||||
|
||||
### 3. Build
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## 🏃 RULARE
|
||||
|
||||
### Development Mode
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
# Server pornește la 127.0.0.1:19017
|
||||
```
|
||||
|
||||
### Production Mode
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
## 🔗 CONECTARE CLAUDE
|
||||
|
||||
### 1. Configurare Claude Settings
|
||||
|
||||
Adaugă în `claude_desktop_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"custom-mcp": {
|
||||
"command": "node",
|
||||
"args": ["/Projects/mcp/dist/server.js"],
|
||||
"env": {
|
||||
"MCP_HOST": "127.0.0.1",
|
||||
"MCP_PORT": "19017"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Restart Claude Desktop
|
||||
|
||||
După configurare, restart aplicația Claude.
|
||||
|
||||
## 🌐 NGINX PROXY SETUP
|
||||
|
||||
Pentru access extern via `mcp.runningwolf.com`:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
server_name mcp.runningwolf.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:19017;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection 'upgrade';
|
||||
proxy_set_header Host $host;
|
||||
proxy_cache_bypass $http_upgrade;
|
||||
}
|
||||
|
||||
# SSL config aici
|
||||
}
|
||||
```
|
||||
|
||||
## 🧪 TESTARE
|
||||
|
||||
```bash
|
||||
# Unit tests
|
||||
npm test
|
||||
|
||||
# Integration tests
|
||||
npm run test:integration
|
||||
|
||||
# Test conexiune
|
||||
curl http://127.0.0.1:19017/health
|
||||
```
|
||||
|
||||
## 🔍 TROUBLESHOOTING
|
||||
|
||||
### Port deja ocupat
|
||||
```bash
|
||||
lsof -i :19017
|
||||
# Kill procesul dacă e necesar
|
||||
```
|
||||
|
||||
### Erori TypeScript
|
||||
```bash
|
||||
npm run typecheck
|
||||
```
|
||||
|
||||
### Logs
|
||||
```bash
|
||||
# Development
|
||||
tail -f logs/mcp-dev.log
|
||||
|
||||
# Production
|
||||
tail -f logs/mcp.log
|
||||
```
|
||||
|
||||
## 🔗 LEGĂTURI
|
||||
|
||||
- [Arhitectură](./ARHITECTURA.md)
|
||||
- [Tools Disponibile](./TOOLS.md)
|
||||
- [Task Management](./TASKS.md)
|
||||
|
||||
---
|
||||
*Actualizat: 25 Iulie 2025*
|
||||
93
docs/TASKS.md
Normal file
93
docs/TASKS.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# 📋 TASK MANAGEMENT & ISTORIE
|
||||
|
||||
## ⚡ REGULI DE AUR (NICIODATA NU ȘTERG!)
|
||||
|
||||
1. **NICI UN TASK NU SE CONSIDERĂ ÎNDEPLINIT** până nu se îndeplinesc criteriile de acceptanță definite
|
||||
2. **NU ÎNCEPEM UN TASK** până nu definim criteriile de acceptanță
|
||||
3. **UN SINGUR TASK ÎN LUCRU** - restul în standby
|
||||
4. **DOCUMENTAȚIA RĂMÂNE ÎN ARBORE** - toate fișierele conectate
|
||||
5. **NU LUCREZI NICIODATĂ LA ALTCEVA** decât ți s-a spus explicit
|
||||
6. **NICIODATA NU HARDCODEZ VARIABILE!**
|
||||
7. **NICIODATA NU ADAUGAM SETARI FAILOVERS** - Dacă ceva nu e bine, vrem să știm imediat
|
||||
8. **Salvez date relevante taskului curent** în DEBUG_CURRENT_TASK.md
|
||||
9. **Salvez întotdeauna ce am modificat** pentru rollback dacă e nevoie
|
||||
10. **Creez criterii de acceptanță** înainte de a testa/finaliza
|
||||
11. **Când task-uri depind de API changes** → salvez în TASK_IN_STANDBY.md
|
||||
|
||||
[← Înapoi la CLAUDE.md](../CLAUDE.md)
|
||||
|
||||
## 🏃 TASK CURENT
|
||||
|
||||
Vezi [DEBUG_CURRENT_TASK.md](../DEBUG_CURRENT_TASK.md)
|
||||
|
||||
## 📌 TASKS ÎN STANDBY
|
||||
|
||||
Vezi [TASK_IN_STANDBY.md](../TASK_IN_STANDBY.md)
|
||||
|
||||
## ✅ TASKS COMPLETATE
|
||||
|
||||
### Task #1: Structura de bază pentru serverul MCP
|
||||
**Completat:** 25 Iulie 2025
|
||||
**Durata:** ~1 oră
|
||||
**Criterii îndeplinite:**
|
||||
- ✅ TypeScript project setup cu configurare strictă
|
||||
- ✅ Server MCP funcțional pe 127.0.0.1:19017
|
||||
- ✅ Structură de bază conform arhitecturii
|
||||
- ✅ NATS connection setup
|
||||
- ✅ MCP SDK integration
|
||||
- ✅ Development workflow
|
||||
- ✅ Teste de bază
|
||||
|
||||
**Fișiere create:**
|
||||
- `package.json`, `tsconfig.json`, `.eslintrc.json`, `.prettierrc.json`
|
||||
- `/src/server.ts` - MCPServer class principal
|
||||
- `/src/config.ts` - Configurare cu Zod
|
||||
- `/src/types/index.ts` - TypeScript interfaces
|
||||
- `/src/nats/NatsClient.ts` - NATS wrapper
|
||||
- `/src/registry/ToolRegistry.ts` - Tool management
|
||||
- `/src/registry/ModuleManager.ts` - Module lifecycle
|
||||
- Teste unitare în `/tests/`
|
||||
|
||||
### Task #5: Sistem Documentație
|
||||
**Completat:** 25 Iulie 2025
|
||||
**Durata:** ~45 minute
|
||||
**Criterii îndeplinite:**
|
||||
- ✅ CLAUDE.md creat cu reguli și structură
|
||||
- ✅ Sistem fișiere arboresecent
|
||||
- ✅ Reguli de aur în toate fișierele
|
||||
- ✅ DEBUG_CURRENT_TASK.md pentru tracking
|
||||
- ✅ TASK_IN_STANDBY.md pentru queue
|
||||
- ✅ Test final: toate fișierele există și sunt conectate
|
||||
|
||||
**Fișiere create:**
|
||||
- `/Projects/mcp/CLAUDE.md`
|
||||
- `/Projects/mcp/DEBUG_CURRENT_TASK.md`
|
||||
- `/Projects/mcp/TASK_IN_STANDBY.md`
|
||||
- `/Projects/mcp/docs/ARHITECTURA.md`
|
||||
- `/Projects/mcp/docs/SETUP.md`
|
||||
- `/Projects/mcp/docs/TOOLS.md`
|
||||
- `/Projects/mcp/docs/TASKS.md` (acest fișier)
|
||||
|
||||
## 📊 METRICI
|
||||
|
||||
- **Total tasks definite:** 5
|
||||
- **Completate:** 1 (în progres)
|
||||
- **În standby:** 4
|
||||
- **Success rate:** TBD
|
||||
|
||||
## 🔄 WORKFLOW PROCESS
|
||||
|
||||
1. **User definește task** → criterii acceptanță
|
||||
2. **Un singur task activ** → în DEBUG_CURRENT_TASK.md
|
||||
3. **Alte tasks** → în TASK_IN_STANDBY.md
|
||||
4. **După completare** → arhivat aici
|
||||
5. **Rollback info** → salvat în fiecare task
|
||||
|
||||
## 🔗 LEGĂTURI
|
||||
|
||||
- [Current Task](../DEBUG_CURRENT_TASK.md)
|
||||
- [Standby Queue](../TASK_IN_STANDBY.md)
|
||||
- [Main Context](../CLAUDE.md)
|
||||
|
||||
---
|
||||
*Actualizat: 25 Iulie 2025*
|
||||
139
docs/TOOLS.md
Normal file
139
docs/TOOLS.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# 🔧 MCP SERVER TOOLS
|
||||
|
||||
## ⚡ REGULI DE AUR (NICIODATA NU ȘTERG!)
|
||||
|
||||
1. **NICI UN TASK NU SE CONSIDERĂ ÎNDEPLINIT** până nu se îndeplinesc criteriile de acceptanță definite
|
||||
2. **NU ÎNCEPEM UN TASK** până nu definim criteriile de acceptanță
|
||||
3. **UN SINGUR TASK ÎN LUCRU** - restul în standby
|
||||
4. **DOCUMENTAȚIA RĂMÂNE ÎN ARBORE** - toate fișierele conectate
|
||||
5. **NU LUCREZI NICIODATĂ LA ALTCEVA** decât ți s-a spus explicit
|
||||
6. **NICIODATA NU HARDCODEZ VARIABILE!**
|
||||
7. **NICIODATA NU ADAUGAM SETARI FAILOVERS** - Dacă ceva nu e bine, vrem să știm imediat
|
||||
8. **Salvez date relevante taskului curent** în DEBUG_CURRENT_TASK.md
|
||||
9. **Salvez întotdeauna ce am modificat** pentru rollback dacă e nevoie
|
||||
10. **Creez criterii de acceptanță** înainte de a testa/finaliza
|
||||
11. **Când task-uri depind de API changes** → salvez în TASK_IN_STANDBY.md
|
||||
|
||||
[← Înapoi la CLAUDE.md](../CLAUDE.md)
|
||||
|
||||
## 📋 TOOL-URI DISPONIBILE
|
||||
|
||||
### ✅ Tool-uri Implementate
|
||||
|
||||
Serverul MCP vine cu un set complet de tool-uri built-in pentru operații comune:
|
||||
|
||||
#### 📁 [File Operations](./tools/file-operations.md)
|
||||
- **file_read** - Citire fișiere cu limite de securitate
|
||||
- **file_write** - Scriere fișiere cu validare
|
||||
- **file_list** - Listare directoare cu filtrare
|
||||
|
||||
#### 💻 [System Command](./tools/system-command.md)
|
||||
- **system_command** - Execuție comenzi sistem (whitelist)
|
||||
|
||||
#### 🌐 [HTTP Request](./tools/http-request.md)
|
||||
- **http_request** - Request-uri HTTP/HTTPS cu securitate
|
||||
|
||||
📚 **[Vezi documentația completă a tool-urilor →](./tools/README.md)**
|
||||
|
||||
## 🎯 TOOL-URI PLANIFICATE
|
||||
|
||||
### 1. File Operations
|
||||
**Nume:** `file_read`, `file_write`, `file_watch`
|
||||
**Scop:** Operații cu fișiere locale
|
||||
**Input Schema:**
|
||||
```json
|
||||
{
|
||||
"path": "string",
|
||||
"encoding": "utf8|binary",
|
||||
"content": "string (pentru write)"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. System Commands
|
||||
**Nume:** `exec_command`
|
||||
**Scop:** Execuție comenzi sistem
|
||||
**Input Schema:**
|
||||
```json
|
||||
{
|
||||
"command": "string",
|
||||
"args": ["array", "of", "strings"],
|
||||
"cwd": "string",
|
||||
"timeout": "number"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. HTTP Client
|
||||
**Nume:** `http_request`
|
||||
**Scop:** Request-uri HTTP/HTTPS
|
||||
**Input Schema:**
|
||||
```json
|
||||
{
|
||||
"url": "string",
|
||||
"method": "GET|POST|PUT|DELETE",
|
||||
"headers": {},
|
||||
"body": "string|object"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Database Query
|
||||
**Nume:** `db_query`
|
||||
**Scop:** Interogări bază de date
|
||||
**Input Schema:**
|
||||
```json
|
||||
{
|
||||
"connection": "string",
|
||||
"query": "string",
|
||||
"params": []
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Data Transform
|
||||
**Nume:** `transform_data`
|
||||
**Scop:** Transformări JSON/CSV
|
||||
**Input Schema:**
|
||||
```json
|
||||
{
|
||||
"input": "object|array",
|
||||
"transform": "jq expression or custom",
|
||||
"output_format": "json|csv|yaml"
|
||||
}
|
||||
```
|
||||
|
||||
## 🔨 CUM SĂ ADAUGI UN TOOL NOU
|
||||
|
||||
1. **Creează fișier** în `src/tools/`
|
||||
2. **Implementează interfața**:
|
||||
```typescript
|
||||
export interface Tool {
|
||||
name: string
|
||||
description: string
|
||||
inputSchema: JSONSchema
|
||||
handler: (input: any) => Promise<any>
|
||||
}
|
||||
```
|
||||
|
||||
3. **Înregistrează în** `src/tools/index.ts`
|
||||
4. **Adaugă teste** în `tests/tools/`
|
||||
5. **Documentează aici** cu exemple
|
||||
|
||||
## 🧪 TESTARE TOOL-URI
|
||||
|
||||
```bash
|
||||
# Test individual tool
|
||||
npm run test:tool -- file_read
|
||||
|
||||
# Test all tools
|
||||
npm run test:tools
|
||||
|
||||
# Integration test cu Claude
|
||||
npm run test:integration
|
||||
```
|
||||
|
||||
## 🔗 LEGĂTURI
|
||||
|
||||
- [Arhitectură](./ARHITECTURA.md)
|
||||
- [Setup Guide](./SETUP.md)
|
||||
- [Task Management](./TASKS.md)
|
||||
|
||||
---
|
||||
*Actualizat: 25 Iulie 2025*
|
||||
443
docs/api-reference.md
Normal file
443
docs/api-reference.md
Normal file
@@ -0,0 +1,443 @@
|
||||
# MCP Server API Reference
|
||||
|
||||
## Tool Handler Base Class
|
||||
|
||||
All tools extend the `ToolHandler` abstract class which provides lifecycle management, validation, and error handling.
|
||||
|
||||
### Class Definition
|
||||
|
||||
```typescript
|
||||
abstract class ToolHandler<TInput = any, TOutput = any> {
|
||||
constructor(
|
||||
config: ToolConfig,
|
||||
inputSchema: z.ZodSchema<TInput>,
|
||||
outputSchema: z.ZodSchema<TOutput>
|
||||
);
|
||||
|
||||
// Main execution method
|
||||
async execute(input: unknown, context: ToolContext): Promise<TOutput>;
|
||||
|
||||
// Lifecycle hooks (override in subclass)
|
||||
protected async initialize(): Promise<void>;
|
||||
protected async validate(input: TInput): Promise<TInput>;
|
||||
protected abstract handle(input: TInput, context: ToolContext): Promise<TOutput>;
|
||||
protected async cleanup(): Promise<void>;
|
||||
protected async checkPermissions(context: ToolContext): Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
### Tool Configuration
|
||||
|
||||
```typescript
|
||||
interface ToolConfig {
|
||||
name: string; // Unique tool identifier
|
||||
description: string; // Human-readable description
|
||||
timeout?: number; // Execution timeout in ms (default: 30000)
|
||||
permissions?: string[]; // Required permissions
|
||||
}
|
||||
```
|
||||
|
||||
### Tool Context
|
||||
|
||||
```typescript
|
||||
interface ToolContext {
|
||||
requestId: string; // Unique request identifier
|
||||
permissions: string[]; // Granted permissions
|
||||
userId?: string; // Optional user identifier
|
||||
metadata?: Record<string, any>; // Additional context
|
||||
}
|
||||
```
|
||||
|
||||
## Creating a Custom Tool
|
||||
|
||||
### Basic Example
|
||||
|
||||
```typescript
|
||||
import { z } from 'zod';
|
||||
import { ToolHandler, ToolContext } from '@mcp/tools';
|
||||
|
||||
// Define schemas
|
||||
const InputSchema = z.object({
|
||||
message: z.string(),
|
||||
uppercase: z.boolean().optional(),
|
||||
});
|
||||
|
||||
const OutputSchema = z.object({
|
||||
result: z.string(),
|
||||
length: z.number(),
|
||||
});
|
||||
|
||||
type Input = z.infer<typeof InputSchema>;
|
||||
type Output = z.infer<typeof OutputSchema>;
|
||||
|
||||
// Implement tool
|
||||
export class EchoTool extends ToolHandler<Input, Output> {
|
||||
constructor() {
|
||||
super(
|
||||
{
|
||||
name: 'echo',
|
||||
description: 'Echo a message with transformations',
|
||||
timeout: 5000,
|
||||
},
|
||||
InputSchema,
|
||||
OutputSchema
|
||||
);
|
||||
}
|
||||
|
||||
protected async handle(input: Input, context: ToolContext): Promise<Output> {
|
||||
let result = input.message;
|
||||
|
||||
if (input.uppercase) {
|
||||
result = result.toUpperCase();
|
||||
}
|
||||
|
||||
this.logger.info({ message: result }, 'Echoing message');
|
||||
|
||||
return {
|
||||
result,
|
||||
length: result.length,
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Advanced Example with Permissions
|
||||
|
||||
```typescript
|
||||
export class DatabaseQueryTool extends ToolHandler<QueryInput, QueryOutput> {
|
||||
private db: Database;
|
||||
|
||||
constructor() {
|
||||
super(
|
||||
{
|
||||
name: 'db_query',
|
||||
description: 'Execute database queries',
|
||||
timeout: 60000,
|
||||
permissions: ['database:read', 'database:write'],
|
||||
},
|
||||
QueryInputSchema,
|
||||
QueryOutputSchema
|
||||
);
|
||||
}
|
||||
|
||||
protected async initialize(): Promise<void> {
|
||||
// Connect to database
|
||||
this.db = await Database.connect(process.env.DATABASE_URL);
|
||||
}
|
||||
|
||||
protected async checkPermissions(context: ToolContext): Promise<void> {
|
||||
const isWrite = this.isWriteQuery(this.currentInput.query);
|
||||
|
||||
if (isWrite && !context.permissions.includes('database:write')) {
|
||||
throw new Error('Permission denied: database:write required');
|
||||
}
|
||||
|
||||
if (!context.permissions.includes('database:read')) {
|
||||
throw new Error('Permission denied: database:read required');
|
||||
}
|
||||
}
|
||||
|
||||
protected async validate(input: QueryInput): Promise<QueryInput> {
|
||||
// Additional validation beyond schema
|
||||
if (this.containsSqlInjection(input.query)) {
|
||||
throw new Error('Invalid query: potential SQL injection');
|
||||
}
|
||||
|
||||
return input;
|
||||
}
|
||||
|
||||
protected async handle(input: QueryInput, context: ToolContext): Promise<QueryOutput> {
|
||||
const startTime = Date.now();
|
||||
|
||||
try {
|
||||
const results = await this.db.query(input.query, input.params);
|
||||
|
||||
return {
|
||||
rows: results.rows,
|
||||
rowCount: results.rowCount,
|
||||
duration: Date.now() - startTime,
|
||||
};
|
||||
} catch (error) {
|
||||
this.logger.error({ error, query: input.query }, 'Query failed');
|
||||
throw new Error(`Database query failed: ${error.message}`);
|
||||
}
|
||||
}
|
||||
|
||||
protected async cleanup(): Promise<void> {
|
||||
// Close database connection
|
||||
if (this.db) {
|
||||
await this.db.close();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Tool Registration
|
||||
|
||||
### Registering Built-in Tools
|
||||
|
||||
```typescript
|
||||
import { ToolRegistry } from '@mcp/registry';
|
||||
import { FileReadTool, FileWriteTool } from './tools';
|
||||
|
||||
const registry = new ToolRegistry(natsClient);
|
||||
|
||||
// Built-in tools are registered automatically
|
||||
// But you can also register manually
|
||||
registry.registerBuiltinTool('file_read', new FileReadTool());
|
||||
registry.registerBuiltinTool('file_write', new FileWriteTool());
|
||||
```
|
||||
|
||||
### Registering External Module Tools
|
||||
|
||||
```typescript
|
||||
// External tools are discovered via NATS
|
||||
// Modules announce their tools on startup
|
||||
natsClient.publish('tools.discovery', {
|
||||
module: 'my-module',
|
||||
tools: [
|
||||
{
|
||||
name: 'my_tool',
|
||||
description: 'Custom tool from module',
|
||||
inputSchema: { /* ... */ },
|
||||
permissions: ['custom:permission'],
|
||||
}
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Error Types
|
||||
|
||||
```typescript
|
||||
// Base error class
|
||||
export class ToolError extends Error {
|
||||
constructor(
|
||||
message: string,
|
||||
public code: string,
|
||||
public details?: any
|
||||
) {
|
||||
super(message);
|
||||
this.name = 'ToolError';
|
||||
}
|
||||
}
|
||||
|
||||
// Specific error types
|
||||
export class ValidationError extends ToolError {
|
||||
constructor(message: string, details?: any) {
|
||||
super(message, 'VALIDATION_ERROR', details);
|
||||
}
|
||||
}
|
||||
|
||||
export class PermissionError extends ToolError {
|
||||
constructor(message: string, required: string[]) {
|
||||
super(message, 'PERMISSION_ERROR', { required });
|
||||
}
|
||||
}
|
||||
|
||||
export class TimeoutError extends ToolError {
|
||||
constructor(timeout: number) {
|
||||
super(`Operation timed out after ${timeout}ms`, 'TIMEOUT_ERROR');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling in Tools
|
||||
|
||||
```typescript
|
||||
protected async handle(input: Input, context: ToolContext): Promise<Output> {
|
||||
try {
|
||||
// Tool logic
|
||||
} catch (error) {
|
||||
if (error.code === 'ENOENT') {
|
||||
throw new ToolError('File not found', 'FILE_NOT_FOUND', { path: input.path });
|
||||
}
|
||||
|
||||
// Re-throw unknown errors
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Tools
|
||||
|
||||
### Unit Testing
|
||||
|
||||
```typescript
|
||||
import { MyTool } from './MyTool';
|
||||
import { ToolContext } from '@mcp/tools';
|
||||
|
||||
describe('MyTool', () => {
|
||||
let tool: MyTool;
|
||||
|
||||
beforeEach(() => {
|
||||
tool = new MyTool();
|
||||
});
|
||||
|
||||
const createContext = (permissions: string[] = []): ToolContext => ({
|
||||
requestId: 'test-request',
|
||||
permissions,
|
||||
});
|
||||
|
||||
it('should execute successfully', async () => {
|
||||
const result = await tool.execute(
|
||||
{ input: 'test' },
|
||||
createContext(['required:permission'])
|
||||
);
|
||||
|
||||
expect(result).toEqual({ output: 'expected' });
|
||||
});
|
||||
|
||||
it('should require permissions', async () => {
|
||||
await expect(
|
||||
tool.execute({ input: 'test' }, createContext())
|
||||
).rejects.toThrow('Permission denied');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Integration Testing
|
||||
|
||||
```typescript
|
||||
import { ToolRegistry } from '@mcp/registry';
|
||||
import { NatsClient } from '@mcp/nats';
|
||||
|
||||
describe('Tool Integration', () => {
|
||||
let registry: ToolRegistry;
|
||||
let nats: NatsClient;
|
||||
|
||||
beforeAll(async () => {
|
||||
nats = new NatsClient();
|
||||
await nats.connect();
|
||||
registry = new ToolRegistry(nats);
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
await nats.close();
|
||||
});
|
||||
|
||||
it('should execute tool via registry', async () => {
|
||||
const result = await registry.executeTool(
|
||||
'my_tool',
|
||||
{ input: 'test' }
|
||||
);
|
||||
|
||||
expect(result).toBeDefined();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Timeout Management
|
||||
|
||||
```typescript
|
||||
protected async handle(input: Input, context: ToolContext): Promise<Output> {
|
||||
// Use AbortController for cancellable operations
|
||||
const controller = new AbortController();
|
||||
|
||||
const timeoutId = setTimeout(
|
||||
() => controller.abort(),
|
||||
this.config.timeout || 30000
|
||||
);
|
||||
|
||||
try {
|
||||
const result = await fetch(input.url, {
|
||||
signal: controller.signal,
|
||||
});
|
||||
|
||||
return processResult(result);
|
||||
} finally {
|
||||
clearTimeout(timeoutId);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Resource Management
|
||||
|
||||
```typescript
|
||||
export class ResourceIntensiveTool extends ToolHandler {
|
||||
private pool: ResourcePool;
|
||||
|
||||
protected async initialize(): Promise<void> {
|
||||
// Initialize resource pool
|
||||
this.pool = new ResourcePool({ max: 10 });
|
||||
}
|
||||
|
||||
protected async handle(input: Input, context: ToolContext): Promise<Output> {
|
||||
// Acquire resource from pool
|
||||
const resource = await this.pool.acquire();
|
||||
|
||||
try {
|
||||
return await this.processWithResource(resource, input);
|
||||
} finally {
|
||||
// Always release resource
|
||||
this.pool.release(resource);
|
||||
}
|
||||
}
|
||||
|
||||
protected async cleanup(): Promise<void> {
|
||||
// Drain pool on cleanup
|
||||
await this.pool.drain();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. **Always validate input** - Use Zod schemas and additional validation
|
||||
2. **Check permissions** - Implement checkPermissions for sensitive operations
|
||||
3. **Sanitize paths** - Prevent directory traversal attacks
|
||||
4. **Limit resource usage** - Implement timeouts and size limits
|
||||
5. **Log security events** - Track permission denials and suspicious activity
|
||||
6. **Use prepared statements** - Prevent SQL injection in database tools
|
||||
7. **Validate URLs** - Block internal/private IP ranges in HTTP tools
|
||||
|
||||
## Debugging Tools
|
||||
|
||||
### Logging
|
||||
|
||||
```typescript
|
||||
protected async handle(input: Input, context: ToolContext): Promise<Output> {
|
||||
this.logger.debug({ input }, 'Processing request');
|
||||
|
||||
try {
|
||||
const result = await this.process(input);
|
||||
this.logger.info({ result }, 'Request successful');
|
||||
return result;
|
||||
} catch (error) {
|
||||
this.logger.error({ error, input }, 'Request failed');
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Metrics
|
||||
|
||||
```typescript
|
||||
protected async handle(input: Input, context: ToolContext): Promise<Output> {
|
||||
const timer = this.metrics.startTimer('tool_execution_duration', {
|
||||
tool: this.config.name,
|
||||
});
|
||||
|
||||
try {
|
||||
const result = await this.process(input);
|
||||
|
||||
this.metrics.increment('tool_execution_success', {
|
||||
tool: this.config.name,
|
||||
});
|
||||
|
||||
return result;
|
||||
} catch (error) {
|
||||
this.metrics.increment('tool_execution_error', {
|
||||
tool: this.config.name,
|
||||
error: error.code,
|
||||
});
|
||||
|
||||
throw error;
|
||||
} finally {
|
||||
timer.end();
|
||||
}
|
||||
}
|
||||
```
|
||||
182
docs/tools/README.md
Normal file
182
docs/tools/README.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# MCP Server Built-in Tools
|
||||
|
||||
The MCP server comes with a comprehensive set of built-in tools for common operations. All tools include security features, permission controls, and consistent error handling.
|
||||
|
||||
## Available Tools
|
||||
|
||||
### 📁 File Operations
|
||||
Tools for reading, writing, and listing files with security controls.
|
||||
|
||||
- [**FileReadTool**](./file-operations.md#filereadtool) - Read file contents
|
||||
- [**FileWriteTool**](./file-operations.md#filewritetool) - Write content to files
|
||||
- [**FileListTool**](./file-operations.md#filelisttool) - List directory contents
|
||||
|
||||
### 💻 System Operations
|
||||
Execute system commands with security restrictions.
|
||||
|
||||
- [**SystemCommandTool**](./system-command.md) - Execute whitelisted system commands
|
||||
|
||||
### 🌐 Network Operations
|
||||
Make HTTP requests to external services.
|
||||
|
||||
- [**HttpRequestTool**](./http-request.md) - Make HTTP/HTTPS requests
|
||||
|
||||
## Permission Model
|
||||
|
||||
Each tool requires specific permissions to execute:
|
||||
|
||||
| Tool | Required Permission | Description |
|
||||
|------|-------------------|-------------|
|
||||
| FileReadTool | `file:read` | Read access to files |
|
||||
| FileWriteTool | `file:write` | Write access to files |
|
||||
| FileListTool | `file:read` | Read access to directories |
|
||||
| SystemCommandTool | `system:exec` | Execute system commands |
|
||||
| HttpRequestTool | `network:http` | Make HTTP requests |
|
||||
|
||||
## Security Features
|
||||
|
||||
All built-in tools implement comprehensive security controls:
|
||||
|
||||
### 🛡️ Path Security
|
||||
- **Directory traversal prevention** - Blocks `..` and absolute paths outside allowed directories
|
||||
- **Restricted directories** - Cannot access system directories like `/etc`, `/sys`, `/proc`
|
||||
- **Allowed paths** - Only current working directory and system temp directory
|
||||
|
||||
### 🔒 Input Validation
|
||||
- **Schema validation** - All inputs validated with Zod schemas
|
||||
- **Command whitelisting** - Only safe system commands allowed
|
||||
- **Shell injection prevention** - Blocks shell operators in arguments
|
||||
- **URL validation** - Validates and blocks private IP ranges
|
||||
|
||||
### ⏱️ Resource Limits
|
||||
- **Timeouts** - All operations have configurable timeouts
|
||||
- **Size limits** - File operations limited to 10MB
|
||||
- **Output limits** - Command output limited to 1MB
|
||||
|
||||
## Error Handling
|
||||
|
||||
All tools follow consistent error handling patterns:
|
||||
|
||||
```javascript
|
||||
try {
|
||||
const result = await mcp.callTool('tool_name', params);
|
||||
// Handle success
|
||||
} catch (error) {
|
||||
// Errors include:
|
||||
// - Permission denied
|
||||
// - Invalid input
|
||||
// - Resource not found
|
||||
// - Timeout exceeded
|
||||
// - Operation failed
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Reading a Configuration File
|
||||
```javascript
|
||||
const config = await mcp.callTool('file_read', {
|
||||
path: './config.json'
|
||||
});
|
||||
const parsedConfig = JSON.parse(config.content);
|
||||
```
|
||||
|
||||
### Writing Log Data
|
||||
```javascript
|
||||
await mcp.callTool('file_write', {
|
||||
path: './logs/app.log',
|
||||
content: `[${new Date().toISOString()}] Application started\n`,
|
||||
mode: 'append'
|
||||
});
|
||||
```
|
||||
|
||||
### Listing Project Files
|
||||
```javascript
|
||||
const files = await mcp.callTool('file_list', {
|
||||
path: './src',
|
||||
recursive: true,
|
||||
pattern: '*.js'
|
||||
});
|
||||
```
|
||||
|
||||
### Running System Commands
|
||||
```javascript
|
||||
const result = await mcp.callTool('system_command', {
|
||||
command: 'grep',
|
||||
args: ['-r', 'TODO', '.'],
|
||||
cwd: './src'
|
||||
});
|
||||
```
|
||||
|
||||
### Making API Requests
|
||||
```javascript
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://api.github.com/user',
|
||||
headers: {
|
||||
'Authorization': 'token YOUR_TOKEN'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always handle errors** - Tools can fail for various reasons
|
||||
2. **Use appropriate timeouts** - Don't let operations hang
|
||||
3. **Validate inputs** - Even though tools validate, check your data
|
||||
4. **Check permissions** - Ensure required permissions are granted
|
||||
5. **Use relative paths** - More portable than absolute paths
|
||||
6. **Respect rate limits** - Especially for HTTP requests
|
||||
7. **Log operations** - Track what tools are doing
|
||||
|
||||
## Extending with Custom Tools
|
||||
|
||||
While built-in tools cover common use cases, you can create custom tools for specific needs. See the [Module Development Guide](../modules/development.md) for details on creating custom tools.
|
||||
|
||||
## Tool Lifecycle
|
||||
|
||||
1. **Input validation** - Schema validation with Zod
|
||||
2. **Permission check** - Verify required permissions
|
||||
3. **Pre-execution hooks** - Custom validation/preparation
|
||||
4. **Execution** - Actual tool operation
|
||||
5. **Output formatting** - Consistent response format
|
||||
6. **Error handling** - Structured error responses
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- File operations are synchronous within the tool
|
||||
- HTTP requests use native fetch API
|
||||
- System commands spawn child processes
|
||||
- All operations subject to timeout limits
|
||||
- Large file operations may impact performance
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Permission Denied
|
||||
```
|
||||
Error: Permission denied: file:read required
|
||||
```
|
||||
Ensure the tool has required permissions in the auth context.
|
||||
|
||||
### Invalid Path
|
||||
```
|
||||
Error: Invalid path: directory traversal not allowed
|
||||
```
|
||||
Use paths within the current directory or temp directory.
|
||||
|
||||
### Command Not Allowed
|
||||
```
|
||||
Error: Command not allowed: rm
|
||||
```
|
||||
Only whitelisted commands can be executed.
|
||||
|
||||
### Timeout Exceeded
|
||||
```
|
||||
Error: Request timeout after 30000ms
|
||||
```
|
||||
Increase timeout or optimize the operation.
|
||||
|
||||
## Version History
|
||||
|
||||
- **v0.1.0** - Initial release with basic file, system, and HTTP tools
|
||||
- **v0.2.0** - Added security controls and permission system
|
||||
- **v0.3.0** - Enhanced error handling and validation
|
||||
165
docs/tools/file-operations.md
Normal file
165
docs/tools/file-operations.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# File Operations Tools
|
||||
|
||||
The MCP server provides several built-in tools for file system operations with comprehensive security controls.
|
||||
|
||||
## FileReadTool
|
||||
|
||||
Reads the contents of a file with security restrictions.
|
||||
|
||||
### Input Schema
|
||||
```typescript
|
||||
{
|
||||
path: string; // File path (relative or absolute)
|
||||
encoding?: 'utf8' | 'binary'; // Default: 'utf8'
|
||||
}
|
||||
```
|
||||
|
||||
### Output Schema
|
||||
```typescript
|
||||
{
|
||||
content: string; // File contents
|
||||
size: number; // File size in bytes
|
||||
path: string; // Absolute file path
|
||||
}
|
||||
```
|
||||
|
||||
### Security Features
|
||||
- Prevents directory traversal attacks
|
||||
- Only allows access to files within current working directory or system temp directory
|
||||
- File size limit: 10MB
|
||||
- Requires `file:read` permission
|
||||
|
||||
### Example Usage
|
||||
```javascript
|
||||
const result = await mcp.callTool('file_read', {
|
||||
path: './config.json',
|
||||
encoding: 'utf8'
|
||||
});
|
||||
console.log(result.content);
|
||||
```
|
||||
|
||||
## FileWriteTool
|
||||
|
||||
Writes content to a file with security restrictions.
|
||||
|
||||
### Input Schema
|
||||
```typescript
|
||||
{
|
||||
path: string; // File path (relative or absolute)
|
||||
content: string; // Content to write
|
||||
encoding?: 'utf8' | 'binary' | 'base64'; // Default: 'utf8'
|
||||
mode?: 'overwrite' | 'append'; // Default: 'overwrite'
|
||||
}
|
||||
```
|
||||
|
||||
### Output Schema
|
||||
```typescript
|
||||
{
|
||||
path: string; // Absolute file path
|
||||
size: number; // File size after write
|
||||
mode: string; // Write mode used
|
||||
}
|
||||
```
|
||||
|
||||
### Security Features
|
||||
- Prevents directory traversal attacks
|
||||
- Only allows writing within current working directory or system temp directory
|
||||
- Blocks writing to system directories (/etc, /sys, /proc, /dev)
|
||||
- Requires `file:write` permission
|
||||
- Automatically creates parent directories if needed
|
||||
|
||||
### Example Usage
|
||||
```javascript
|
||||
// Write text file
|
||||
await mcp.callTool('file_write', {
|
||||
path: './output.txt',
|
||||
content: 'Hello, World!'
|
||||
});
|
||||
|
||||
// Write binary file
|
||||
await mcp.callTool('file_write', {
|
||||
path: './image.png',
|
||||
content: 'iVBORw0KGgoAAAANS...', // base64 encoded
|
||||
encoding: 'base64'
|
||||
});
|
||||
|
||||
// Append to file
|
||||
await mcp.callTool('file_write', {
|
||||
path: './log.txt',
|
||||
content: 'New log entry\n',
|
||||
mode: 'append'
|
||||
});
|
||||
```
|
||||
|
||||
## FileListTool
|
||||
|
||||
Lists files and directories with filtering options.
|
||||
|
||||
### Input Schema
|
||||
```typescript
|
||||
{
|
||||
path: string; // Directory path
|
||||
recursive?: boolean; // Recurse into subdirectories
|
||||
pattern?: string; // Glob pattern filter (e.g., '*.txt')
|
||||
includeHidden?: boolean; // Include hidden files (starting with .)
|
||||
}
|
||||
```
|
||||
|
||||
### Output Schema
|
||||
```typescript
|
||||
{
|
||||
path: string; // Directory path
|
||||
entries: Array<{
|
||||
path: string; // Full path
|
||||
type: 'file' | 'directory' | 'symlink' | 'other';
|
||||
name: string; // File/directory name
|
||||
size: number; // Size in bytes
|
||||
modified: string; // ISO date string
|
||||
}>;
|
||||
totalSize: number; // Total size of all files
|
||||
}
|
||||
```
|
||||
|
||||
### Security Features
|
||||
- Prevents directory traversal attacks
|
||||
- Only allows listing within current working directory or system temp directory
|
||||
- Requires `file:read` permission
|
||||
- Skips inaccessible items instead of failing
|
||||
|
||||
### Example Usage
|
||||
```javascript
|
||||
// List directory contents
|
||||
const result = await mcp.callTool('file_list', {
|
||||
path: './src'
|
||||
});
|
||||
|
||||
// List recursively with pattern
|
||||
const jsFiles = await mcp.callTool('file_list', {
|
||||
path: './src',
|
||||
recursive: true,
|
||||
pattern: '*.js'
|
||||
});
|
||||
|
||||
// Include hidden files
|
||||
const allFiles = await mcp.callTool('file_list', {
|
||||
path: './',
|
||||
includeHidden: true
|
||||
});
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
All file operation tools follow consistent error handling:
|
||||
|
||||
- **File not found**: Returns clear error message with the path
|
||||
- **Permission denied**: Returns error when lacking required permissions
|
||||
- **Invalid paths**: Blocks directory traversal and system paths
|
||||
- **Size limits**: Enforces reasonable limits to prevent abuse
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always use relative paths** when possible for better portability
|
||||
2. **Check permissions** before attempting operations
|
||||
3. **Handle errors gracefully** - file operations can fail for many reasons
|
||||
4. **Use appropriate encodings** - utf8 for text, base64 for binary data
|
||||
5. **Be mindful of file sizes** - large files can impact performance
|
||||
273
docs/tools/http-request.md
Normal file
273
docs/tools/http-request.md
Normal file
@@ -0,0 +1,273 @@
|
||||
# HTTP Request Tool
|
||||
|
||||
Make HTTP/HTTPS requests with comprehensive options and security controls.
|
||||
|
||||
## Overview
|
||||
|
||||
The HttpRequestTool enables making HTTP requests to external services with support for various methods, headers, authentication, and response handling.
|
||||
|
||||
## Input Schema
|
||||
|
||||
```typescript
|
||||
{
|
||||
url: string; // Target URL (required)
|
||||
method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
|
||||
headers?: Record<string, string>; // Request headers
|
||||
body?: string | object; // Request body
|
||||
timeout?: number; // Timeout in ms (default: 30000)
|
||||
followRedirects?: boolean; // Follow redirects (default: true)
|
||||
}
|
||||
```
|
||||
|
||||
## Output Schema
|
||||
|
||||
```typescript
|
||||
{
|
||||
status: number; // HTTP status code
|
||||
statusText: string; // Status message
|
||||
headers: Record<string, string>; // Response headers
|
||||
body: any; // Response body (parsed based on content-type)
|
||||
duration: number; // Request duration in ms
|
||||
}
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
### Supported Methods
|
||||
- **GET** - Retrieve data
|
||||
- **POST** - Submit data
|
||||
- **PUT** - Update resource
|
||||
- **DELETE** - Remove resource
|
||||
- **PATCH** - Partial update
|
||||
- **HEAD** - Headers only
|
||||
- **OPTIONS** - Check allowed methods
|
||||
|
||||
### Automatic Content Handling
|
||||
- JSON responses are automatically parsed
|
||||
- Text responses returned as strings
|
||||
- Binary data returned as base64 encoded strings
|
||||
- Content-Type header automatically set for JSON bodies
|
||||
|
||||
### Security Features
|
||||
- Blocks requests to private IP ranges (localhost, internal networks)
|
||||
- Validates URLs before making requests
|
||||
- Timeout protection against hanging requests
|
||||
- Requires `network:http` permission
|
||||
|
||||
## Example Usage
|
||||
|
||||
### Simple GET Request
|
||||
```javascript
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://api.example.com/users'
|
||||
});
|
||||
console.log(response.body); // Parsed JSON
|
||||
```
|
||||
|
||||
### POST with JSON Body
|
||||
```javascript
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://api.example.com/users',
|
||||
method: 'POST',
|
||||
body: {
|
||||
name: 'John Doe',
|
||||
email: 'john@example.com'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Custom Headers
|
||||
```javascript
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://api.example.com/data',
|
||||
headers: {
|
||||
'Authorization': 'Bearer token123',
|
||||
'X-API-Key': 'myapikey'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Form Data
|
||||
```javascript
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://api.example.com/form',
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/x-www-form-urlencoded'
|
||||
},
|
||||
body: 'name=John&email=john@example.com'
|
||||
});
|
||||
```
|
||||
|
||||
### With Timeout
|
||||
```javascript
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://slow-api.example.com/data',
|
||||
timeout: 5000 // 5 seconds
|
||||
});
|
||||
```
|
||||
|
||||
### Disable Redirect Following
|
||||
```javascript
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://example.com/redirect',
|
||||
followRedirects: false
|
||||
});
|
||||
// Check response.status for 301/302
|
||||
```
|
||||
|
||||
## Response Handling
|
||||
|
||||
### JSON Response
|
||||
```javascript
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://api.example.com/json'
|
||||
});
|
||||
// response.body is already parsed object
|
||||
console.log(response.body.data);
|
||||
```
|
||||
|
||||
### Text Response
|
||||
```javascript
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://example.com/text.txt'
|
||||
});
|
||||
// response.body is string
|
||||
console.log(response.body);
|
||||
```
|
||||
|
||||
### Binary Response
|
||||
```javascript
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://example.com/image.png'
|
||||
});
|
||||
// response.body is base64 encoded string
|
||||
const buffer = Buffer.from(response.body, 'base64');
|
||||
```
|
||||
|
||||
### Status Checking
|
||||
```javascript
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://api.example.com/resource'
|
||||
});
|
||||
|
||||
if (response.status >= 200 && response.status < 300) {
|
||||
// Success
|
||||
} else if (response.status === 404) {
|
||||
// Not found
|
||||
} else if (response.status >= 500) {
|
||||
// Server error
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Network Errors
|
||||
```javascript
|
||||
try {
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://nonexistent.example.com'
|
||||
});
|
||||
} catch (error) {
|
||||
// Error: HTTP request failed: ...
|
||||
}
|
||||
```
|
||||
|
||||
### Timeout Errors
|
||||
```javascript
|
||||
try {
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://slow.example.com',
|
||||
timeout: 1000
|
||||
});
|
||||
} catch (error) {
|
||||
// Error: Request timeout after 1000ms
|
||||
}
|
||||
```
|
||||
|
||||
### Invalid URLs
|
||||
```javascript
|
||||
try {
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'not-a-url'
|
||||
});
|
||||
} catch (error) {
|
||||
// Error: Invalid URL
|
||||
}
|
||||
```
|
||||
|
||||
### Blocked Internal IPs
|
||||
```javascript
|
||||
try {
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'http://192.168.1.1/admin'
|
||||
});
|
||||
} catch (error) {
|
||||
// Error: Requests to private IP ranges are not allowed
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always set appropriate timeouts** for external requests
|
||||
2. **Handle all status codes** - don't assume 200 OK
|
||||
3. **Use HTTPS** when possible for security
|
||||
4. **Set User-Agent** header to identify your application
|
||||
5. **Implement retry logic** for transient failures
|
||||
6. **Respect rate limits** of external APIs
|
||||
7. **Validate response data** before using it
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### API Authentication
|
||||
```javascript
|
||||
// Bearer Token
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://api.example.com/protected',
|
||||
headers: {
|
||||
'Authorization': 'Bearer your-token-here'
|
||||
}
|
||||
});
|
||||
|
||||
// API Key
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://api.example.com/data',
|
||||
headers: {
|
||||
'X-API-Key': 'your-api-key'
|
||||
}
|
||||
});
|
||||
|
||||
// Basic Auth
|
||||
const credentials = Buffer.from('username:password').toString('base64');
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: 'https://api.example.com/secure',
|
||||
headers: {
|
||||
'Authorization': `Basic ${credentials}`
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Pagination
|
||||
```javascript
|
||||
let allData = [];
|
||||
let page = 1;
|
||||
let hasMore = true;
|
||||
|
||||
while (hasMore) {
|
||||
const response = await mcp.callTool('http_request', {
|
||||
url: `https://api.example.com/items?page=${page}&limit=100`
|
||||
});
|
||||
|
||||
allData = allData.concat(response.body.items);
|
||||
hasMore = response.body.hasNextPage;
|
||||
page++;
|
||||
}
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
- Cannot access localhost or private networks
|
||||
- Maximum timeout of 5 minutes
|
||||
- No support for streaming responses
|
||||
- No built-in retry mechanism
|
||||
- No connection pooling or keep-alive
|
||||
186
docs/tools/system-command.md
Normal file
186
docs/tools/system-command.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# System Command Tool
|
||||
|
||||
Execute system commands with comprehensive security controls and output handling.
|
||||
|
||||
## Overview
|
||||
|
||||
The SystemCommandTool allows controlled execution of whitelisted system commands with proper security boundaries, timeout handling, and output management.
|
||||
|
||||
## Input Schema
|
||||
|
||||
```typescript
|
||||
{
|
||||
command: string; // Command to execute (must be whitelisted)
|
||||
args?: string[]; // Command arguments
|
||||
cwd?: string; // Working directory
|
||||
env?: Record<string, string>; // Environment variables
|
||||
timeout?: number; // Timeout in ms (100-300000, default: 30000)
|
||||
stdin?: string; // Input to send to stdin
|
||||
}
|
||||
```
|
||||
|
||||
## Output Schema
|
||||
|
||||
```typescript
|
||||
{
|
||||
stdout: string; // Standard output
|
||||
stderr: string; // Standard error output
|
||||
exitCode: number; // Process exit code
|
||||
duration: number; // Execution time in ms
|
||||
}
|
||||
```
|
||||
|
||||
## Whitelisted Commands
|
||||
|
||||
Only the following commands are allowed for security:
|
||||
|
||||
- `ls` - List directory contents
|
||||
- `cat` - Display file contents
|
||||
- `grep` - Search text patterns
|
||||
- `find` - Find files and directories
|
||||
- `echo` - Print text
|
||||
- `pwd` - Print working directory
|
||||
- `whoami` - Show current user
|
||||
- `date` - Show current date/time
|
||||
- `env` - Show environment variables
|
||||
- `which` - Find command location
|
||||
- `wc` - Word/line/character count
|
||||
- `head` - Show first lines
|
||||
- `tail` - Show last lines
|
||||
- `sort` - Sort lines
|
||||
- `uniq` - Remove duplicate lines
|
||||
- `curl` - HTTP requests
|
||||
- `ping` - Network connectivity test
|
||||
- `dig` - DNS lookup
|
||||
- `ps` - Process list
|
||||
- `df` - Disk usage
|
||||
- `du` - Directory size
|
||||
- `uptime` - System uptime
|
||||
|
||||
## Security Features
|
||||
|
||||
### Command Validation
|
||||
- Only whitelisted commands can be executed
|
||||
- Shell operators (`|`, `&`, `;`, `>`, `<`, etc.) are blocked in arguments
|
||||
- Prevents command injection attacks
|
||||
|
||||
### Resource Limits
|
||||
- Configurable timeout (max 5 minutes)
|
||||
- Output size limited to 1MB per stream
|
||||
- Process is killed if limits exceeded
|
||||
|
||||
### Permission Control
|
||||
- Requires `system:exec` permission
|
||||
- Inherits process environment with modifications
|
||||
|
||||
## Example Usage
|
||||
|
||||
### Basic Command
|
||||
```javascript
|
||||
const result = await mcp.callTool('system_command', {
|
||||
command: 'ls',
|
||||
args: ['-la', '/tmp']
|
||||
});
|
||||
console.log(result.stdout);
|
||||
```
|
||||
|
||||
### With Working Directory
|
||||
```javascript
|
||||
const result = await mcp.callTool('system_command', {
|
||||
command: 'grep',
|
||||
args: ['-r', 'TODO', '.'],
|
||||
cwd: '/home/user/project'
|
||||
});
|
||||
```
|
||||
|
||||
### With Environment Variables
|
||||
```javascript
|
||||
const result = await mcp.callTool('system_command', {
|
||||
command: 'echo',
|
||||
args: ['$MY_VAR'],
|
||||
env: {
|
||||
MY_VAR: 'Hello from environment!'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### With Timeout
|
||||
```javascript
|
||||
const result = await mcp.callTool('system_command', {
|
||||
command: 'find',
|
||||
args: ['/', '-name', '*.log'],
|
||||
timeout: 5000 // 5 seconds
|
||||
});
|
||||
```
|
||||
|
||||
### With stdin Input
|
||||
```javascript
|
||||
const result = await mcp.callTool('system_command', {
|
||||
command: 'grep',
|
||||
args: ['error'],
|
||||
stdin: 'line 1\nerror on line 2\nline 3'
|
||||
});
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Command Not Allowed
|
||||
```javascript
|
||||
// This will throw an error
|
||||
await mcp.callTool('system_command', {
|
||||
command: 'rm' // Not in whitelist
|
||||
});
|
||||
// Error: Command not allowed: rm
|
||||
```
|
||||
|
||||
### Shell Injection Prevention
|
||||
```javascript
|
||||
// This will throw an error
|
||||
await mcp.callTool('system_command', {
|
||||
command: 'ls',
|
||||
args: ['; rm -rf /'] // Shell operators blocked
|
||||
});
|
||||
// Error: Shell characters not allowed in arguments
|
||||
```
|
||||
|
||||
### Timeout Handling
|
||||
```javascript
|
||||
try {
|
||||
await mcp.callTool('system_command', {
|
||||
command: 'find',
|
||||
args: ['/'],
|
||||
timeout: 1000 // 1 second
|
||||
});
|
||||
} catch (error) {
|
||||
// Error: Command timed out after 1000ms
|
||||
}
|
||||
```
|
||||
|
||||
### Non-Zero Exit Codes
|
||||
Non-zero exit codes don't throw errors but are returned in the result:
|
||||
```javascript
|
||||
const result = await mcp.callTool('system_command', {
|
||||
command: 'grep',
|
||||
args: ['nonexistent', 'file.txt']
|
||||
});
|
||||
// result.exitCode will be 1 or 2
|
||||
// result.stderr will contain the error message
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use specific commands** instead of shell scripts
|
||||
2. **Set appropriate timeouts** for long-running commands
|
||||
3. **Check exit codes** to handle command failures
|
||||
4. **Limit output size** by using head/tail when appropriate
|
||||
5. **Avoid user input** in command arguments without validation
|
||||
6. **Use working directory** instead of cd commands
|
||||
7. **Monitor stderr** for warnings and errors
|
||||
|
||||
## Limitations
|
||||
|
||||
- No shell features (pipes, redirects, wildcards)
|
||||
- No interactive commands
|
||||
- No sudo or privileged operations
|
||||
- Output limited to 1MB per stream
|
||||
- Maximum timeout of 5 minutes
|
||||
Reference in New Issue
Block a user