@mcp-tools/shared

Shared utilities, types, and integration layer for building modular, high-performance MCP (Model Context Protocol) tools.

🚀 Features

- 🏗️ Modular Architecture: Build MCPs that work together seamlessly
- ⚡ Performance Optimizations: Caching, batching, parallel processing
- 🔄 Inter-MCP Communication: Pipelines, workflows, and event bus
- 📦 File System Optimization: Smart caching and batch operations
- 📊 Performance Monitoring: Track metrics and optimize bottlenecks
- 🎯 Type Safety: Comprehensive TypeScript types for all operations

📦 Installation

``bash
npm install @mcp-tools/shared
`

For monorepo development:

`json
{
"dependencies": {
"@mcp-tools/shared": "workspace:*"
}
}
`

🎯 Quick Start

$3

`typescript
import { FileSystemManager, generateHash } from '@mcp-tools/shared';

const fsManager = new FileSystemManager(500); // Cache 500 files

// Read file with automatic caching
const content = await fsManager.readFile('./src/index.ts', true);

// Batch read with parallel processing
const files = await fsManager.findFiles('*/.ts', {
ignore: ['node_modules/**'],
});

const contents = await fsManager.readFiles(files, {
useCache: true,
concurrency: 10,
});
`

$3

`typescript
import { AnalysisCache, generateHash } from '@mcp-tools/shared';

const cache = new AnalysisCache(200, 1800000); // 200 entries, 30min TTL

async function analyzeCode(filePath: string, content: string) {
const fileHash = generateHash(content);

// Check cache first
const cached = cache.get(filePath, 'complexity', fileHash);
if (cached) {
return cached;
}

// Perform expensive analysis
const result = await performComplexityAnalysis(content);

// Cache for future use
cache.set(filePath, 'complexity', fileHash, result);

return result;
}
`

$3

`typescript
import { MCPPipeline } from '@mcp-tools/shared';

const pipeline = new MCPPipeline();

pipeline
.addStep({
name: 'analyze',
tool: 'architecture-analyzer',
execute: async input => {
// Analyze project architecture
return { complexity: 45, modularity: 78 };
},
})
.addStep({
name: 'review',
tool: 'smart-reviewer',
dependsOn: ['analyze'],
execute: async input => {
// Review based on architecture analysis
const archResults = input[0];
return { issues: [], score: archResults.data.modularity };
},
});

const result = await pipeline.execute();
console.log(Completed ${result.steps.length} steps in ${result.totalDuration}ms);
`

📚 Core Modules

$3

Optimized file operations with caching and batch processing.

`typescript
import { FileSystemManager, FileWatcher, BatchFileOperations } from '@mcp-tools/shared';

// File system manager
const fs = new FileSystemManager(500);
const content = await fs.readFile(path, true); // With caching
await fs.writeFile(path, content);

// File watcher with debouncing
const watcher = new FileWatcher(500); // 500ms debounce
watcher.watch('./src', (event, filename) => {
console.log(${event}: ${filename});
});

// Batch operations
const batch = new BatchFileOperations();
await batch.writeMultiple(
[
{ path: './file1.ts', content: 'code1' },
{ path: './file2.ts', content: 'code2' },
],
{ concurrency: 5 }
);
`

$3

High-performance LRU caching for files and analysis results.

`typescript
import { MemoryCache, FileCache, AnalysisCache } from '@mcp-tools/shared';

// Generic memory cache
const cache = new MemoryCache({ max: 1000, ttl: 3600000 });
cache.set('key', 'value', 60000); // 60s TTL
const value = cache.get('key');

// File content cache with hash-based invalidation
const fileCache = new FileCache(500);
fileCache.set(filePath, content);
const cached = fileCache.get(filePath, currentHash);

// Analysis result cache
const analysisCache = new AnalysisCache(200, 1800000);
analysisCache.set(filePath, 'complexity', fileHash, result);
const result = analysisCache.get(filePath, 'complexity', fileHash);

// Cache statistics
const stats = cache.getStats();
console.log(Hit rate: ${stats.hitRate}%);
`

$3

Monitor and optimize execution performance.

`typescript
import { PerformanceMonitor, measure, batchProcess, parallelProcess } from '@mcp-tools/shared';

// Performance monitoring
const monitor = new PerformanceMonitor();
monitor.start();
monitor.mark('checkpoint-1');
const metrics = monitor.stop();
console.log(Duration: ${metrics.duration}ms);

// Measure function execution
const { result, duration } = await measure(async () => expensiveOperation(), 'operation-name');

// Batch processing with concurrency limit
const results = await batchProcess(items, async item => processItem(item), {
concurrency: 5,
onProgress: (completed, total) => console.log(${completed}/${total}),
});

// Parallel processing
const results = await parallelProcess(
items,
async (item, index) => processItem(item),
10 // max concurrency
);
`

$3

Orchestrate multiple MCP tools working together.

`typescript
import { MCPPipeline, MCPIntegration, MCPWorkflow, MCPEventBus } from '@mcp-tools/shared';

// Pipeline: Sequential with dependencies
const pipeline = new MCPPipeline();
pipeline.addStep({
name: 'step1',
execute: async () => {
/.../
},
});
const result = await pipeline.execute();

// Integration: Register and call tools
const integration = new MCPIntegration();
integration.registerTool('tool-name', toolInstance);

// Run in parallel
await integration.parallel([
{ tool: 'tool1', method: 'analyze', args: [file1] },
{ tool: 'tool2', method: 'analyze', args: [file2] },
]);

// Chain operations
await integration.chain(initialInput, [
{ tool: 'tool1', method: 'process' },
{ tool: 'tool2', method: 'transform', transform: data => data.output },
]);

// Workflow: Conditional execution
const workflow = new MCPWorkflow('my-workflow');
workflow
.step('scan', 'security-scanner', 'scan')
.step('test', 'test-generator', 'generate', {}, results => {
return results['scan'].data.vulnerabilities.length > 0;
});

// Event bus: Loosely coupled communication
const eventBus = new MCPEventBus();
eventBus.on('file:changed', data => {
console.log('File changed:', data.filePath);
});
eventBus.emit('file:changed', { filePath: './src/index.ts' });
`

$3

Common utility functions for MCP development.

`typescript
import {
generateHash,
normalizePath,
isPathSafe,
retry,
deepMerge,
formatBytes,
truncateString,
safeJsonParse,
} from '@mcp-tools/shared';

// Hash generation
const hash = generateHash(content); // SHA-256

// Path utilities
const normalized = normalizePath('/path/to/file');
const isSafe = isPathSafe(userPath, baseDir); // Prevent path traversal

// Retry with exponential backoff
const result = await retry(
async () => unstableOperation(),
3, // max retries
1000 // initial delay
);

// Deep merge objects
const merged = deepMerge(obj1, obj2, obj3);

// Formatting
formatBytes(1024); // "1.00 KB"
truncateString('long text...', 50);

// Safe JSON parsing
const { data, error } = safeJsonParse(jsonString);
`

$3

Standardized TypeScript interfaces for all MCPs.

`typescript
import {
MCPResult,
MCPConfig,
CodeAnalysisResult,
FileInfo,
PerformanceMetrics,
PipelineStep,
CacheEntry,
} from '@mcp-tools/shared';

// Standard MCP result
const result: MCPResult = {
success: true,
data: myData,
warnings: ['warning message'],
metadata: { version: '1.0.0' },
timestamp: new Date().toISOString(),
};

// Standard MCP configuration
const config: MCPConfig = {
verbose: true,
dryRun: false,
outputFormat: 'json',
cache: true,
parallel: true,
maxConcurrency: 10,
};
`

$3

Shared constants across all MCP tools.

`typescript
import {
FILE_EXTENSIONS,
IGNORE_PATTERNS,
PERFORMANCE,
QUALITY_THRESHOLDS,
SEVERITY,
MCP_TOOLS,
REGEX,
ERROR_CODE,
} from '@mcp-tools/shared';

// File extensions
FILE_EXTENSIONS.TYPESCRIPT; // ['.ts', '.tsx']
FILE_EXTENSIONS.ALL_CODE; // ['.ts', '.tsx', '.js', '.jsx', ...]

// Performance limits
PERFORMANCE.MAX_FILE_SIZE; // 10MB
PERFORMANCE.DEFAULT_CONCURRENCY; // 5

// Quality thresholds
QUALITY_THRESHOLDS.MAX_COMPLEXITY; // 10
QUALITY_THRESHOLDS.MAX_LINE_LENGTH; // 120
QUALITY_THRESHOLDS.MIN_TEST_COVERAGE; // 80

// Common regex patterns
REGEX.TODO_COMMENT; // /\b(TODO|FIXME|XXX|HACK|NOTE)\b/gi
REGEX.CONSOLE_LOG; // /console\.(log|warn|error|debug|info)/g

// MCP tool names
MCP_TOOLS.ARCHITECTURE_ANALYZER; // 'architecture-analyzer'
MCP_TOOLS.SMART_REVIEWER; // 'smart-reviewer'
`

🎯 Common Patterns

$3

`typescript
import { FileSystemManager, AnalysisCache, generateHash, MCPResult } from '@mcp-tools/shared';

export class MyMCPTool {
private fsManager: FileSystemManager;
private cache: AnalysisCache;

constructor() {
this.fsManager = new FileSystemManager(500);
this.cache = new AnalysisCache(200, 1800000);
}

async analyze(filePath: string): Promise {
// Read with caching
const content = await this.fsManager.readFile(filePath, true);
const fileHash = generateHash(content);

// Check cache
const cached = this.cache.get(filePath, 'my-analysis', fileHash);
if (cached) {
return cached;
}

// Perform analysis
const result = await this.performAnalysis(content);

// Cache result
this.cache.set(filePath, 'my-analysis', fileHash, result);

return result;
}
}
`

$3

`typescript
import { FileSystemManager, batchProcess } from '@mcp-tools/shared';

async function processProject(projectPath: string) {
const fsManager = new FileSystemManager();

// Find all TypeScript files
const files = await fsManager.findFiles('*/.ts', {
cwd: projectPath,
ignore: ['node_modules/', 'dist/'],
});

// Process in batches
const results = await batchProcess(
files,
async file => {
const content = await fsManager.readFile(file, true);
return analyzeFile(content);
},
{
concurrency: 10,
onProgress: (completed, total) => {
console.log(Progress: ${completed}/${total});
},
}
);

return results;
}
`

$3

`typescript
import { MCPPipeline, MCPIntegration } from '@mcp-tools/shared';

// Create integration manager
const integration = new MCPIntegration();
integration.registerTool('arch-analyzer', new ArchAnalyzer());
integration.registerTool('reviewer', new SmartReviewer());
integration.registerTool('refactorer', new RefactorAssistant());

// Create pipeline
const pipeline = new MCPPipeline();

pipeline
.addStep({
name: 'analyze',
tool: 'arch-analyzer',
execute: async () => {
const tool = integration.getTool('arch-analyzer');
return tool.analyze('./src');
},
})
.addStep({
name: 'review',
tool: 'reviewer',
dependsOn: ['analyze'],
execute: async input => {
const archResults = input[0];
const tool = integration.getTool('reviewer');
return tool.review(archResults.data.problematicFiles);
},
})
.addStep({
name: 'refactor',
tool: 'refactorer',
dependsOn: ['review'],
execute: async input => {
const reviewResults = input[0];
const tool = integration.getTool('refactorer');
return tool.suggestRefactorings(reviewResults.data.issues);
},
});

const result = await pipeline.execute();
`

$3

`typescript
import { MCPEventBus, FileWatcher, EVENT_TYPE } from '@mcp-tools/shared';

const eventBus = new MCPEventBus();
const watcher = new FileWatcher(500);

// Tool 1: Watch for file changes
watcher.watch(
'./src',
(event, filename) => {
eventBus.emit(EVENT_TYPE.FILE_CHANGED, {
event,
filePath: filename,
timestamp: new Date().toISOString(),
});
},
{ recursive: true }
);

// Tool 2: Analyze on file change
eventBus.on(EVENT_TYPE.FILE_CHANGED, async data => {
const result = await analyzer.analyze(data.filePath);
eventBus.emit(EVENT_TYPE.ANALYSIS_COMPLETED, { result });
});

// Tool 3: Generate tests on analysis completion
eventBus.on(EVENT_TYPE.ANALYSIS_COMPLETED, async data => {
if (data.result.issues.length > 0) {
await testGenerator.generateTests(data.result);
}
});
`

📊 Performance Benchmarks

Typical performance improvements with shared utilities:

| Operation | Without Cache | With Cache | Improvement |
| --------------------- | ------------- | ---------- | ----------- |
| File Read (single) | 5-10ms | <1ms | 90%+ |
| File Read (batch 100) | 500-1000ms | 50-100ms | 80-90% |
| Analysis (repeated) | 100-200ms | <5ms | 95%+ |
| Find Files (glob) | 50-100ms | 10-20ms | 70-80% |

Cache hit rates in production: 80-95%

🔍 Examples

See the examples/ directory for complete working examples:

- 01-pipeline-example.ts: Chaining multiple MCPs in sequence
- 02-workflow-example.ts: Conditional workflows with dependencies
- 03-caching-example.ts: Performance optimization with caching
- 04-event-bus-example.ts: Real-time event-driven architecture

🛠️ Development

$3

`bash
npm run build
`

$3

`bash


Individual examples

npx tsx examples/01-pipeline-example.ts
npx tsx examples/02-workflow-example.ts

All examples

npm run examples
`

$3

`bash
npm test
`

📖 API Documentation

$3

`typescript
class FileSystemManager {
constructor(cacheSize?: number);
readFile(filePath: string, useCache?: boolean): Promise;
readFiles(filePaths: string[], options?: ReadOptions): Promise>;
writeFile(filePath: string, content: string, baseDir?: string): Promise;
findFiles(patterns: string | string[], options?: FindOptions): Promise;
exists(filePath: string): Promise;
clearCache(): void;
getCacheStats(): CacheStats;
}
`

$3

`typescript
class AnalysisCache {
constructor(maxSize?: number, ttl?: number);
get(filePath: string, analysisType: string, fileHash: string, config?: any): any | undefined;
set(filePath: string, analysisType: string, fileHash: string, result: any, config?: any): void;
has(filePath: string, analysisType: string, fileHash: string, config?: any): boolean;
invalidate(filePath: string): void;
clear(): void;
getStats(): CacheStats;
}
`

$3

`typescript
class MCPPipeline {
addStep(step: PipelineStep): this;
execute(): Promise;
getResult(stepName: string): MCPResult | undefined;
getAllResults(): Map;
clear(): void;
}
`

$3

`typescript
class MCPIntegration {
registerTool(name: string, tool: any): void;
getTool(name: string): any;
sequence(steps: SequenceStep[]): Promise;
parallel(steps: ParallelStep[]): Promise;
chain(initialInput: any, operations: ChainOperation[]): Promise;
}
`

$3

`typescript
class PerformanceMonitor {
start(): void;
stop(): PerformanceMetrics;
mark(name: string): void;
getMetrics(name: string): MetricsSummary | null;
getAllMetrics(): Record;
reset(): void;
}
`

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit changes: git commit -am 'Add feature'
4. Push to branch: git push origin feature/my-feature`
5. Submit a pull request

📝 License

MIT License - see LICENSE for details

🔗 Related Packages

This shared package is used by:

- @j0kz/architecture-analyzer-mcp
- @j0kz/smart-reviewer-mcp
- @j0kz/test-generator-mcp
- @j0kz/security-scanner-mcp
- @j0kz/api-designer-mcp
- @j0kz/db-schema-mcp
- @j0kz/doc-generator-mcp
- @j0kz/refactor-assistant-mcp

📞 Support

- GitHub Issues
- Documentation

---

Built with ❤️ for the MCP community