@fractalizer/mcp-infrastructure

Reusable infrastructure layer: HTTP, cache, logging, async utilities


---

🎯 Purpose

Principle: Infrastructure layer does NOT know about domain (Yandex.Tracker, MCP)

Reusability: All components can be used in other projects without modifications

Architecture rule: Infrastructure does NOT import domain-specific code

---

📦 Installation

``bash
npm install @fractalizer/mcp-infrastructure
`

Dependencies: 0 framework dependencies (only external libs: axios, pino, rotating-file-stream)

---

📁 Structure

`
src/
├── http/ # HTTP client + retry + error mapping
│ ├── client/
│ │ └── http-client.ts # Axios wrapper
│ ├── retry/
│ │ ├── retry-handler.ts
│ │ └── exponential-backoff.strategy.ts
│ └── error/
│ └── error-mapper.ts # AxiosError → ApiError
├── cache/ # Caching (Strategy Pattern)
│ ├── cache-manager.interface.ts
│ ├── entity-cache-key.ts # Cache key generator for entities
│ └── no-op-cache.ts # Null Object
├── async/ # Parallel execution
│ └── parallel-executor.ts # Throttling for batch requests
├── logging/ # Production logging (Pino)
│ └── README.md # Detailed docs
├── types.ts # Type definitions
└── index.ts # Public exports
`

---

🔧 Components

$3

AxiosHttpClient (alias HttpClient) — Axios wrapper with built-in retry and error mapping

Key features:
- ✅ Automatic retry via RetryHandler
- ✅ AxiosError → ApiError mapping
- ✅ Request/response logging via interceptors
- ✅ Type-safe generic methods: get(), post(), patch(), delete()

Implementation: src/http/client/axios-http-client.ts

Interface:
`typescript
interface IHttpClient {
get(path: string, params?: QueryParams): Promise;
post(path: string, data?: unknown): Promise;
patch(path: string, data?: unknown): Promise;
delete(path: string): Promise;
}
`

$3

CacheManager — interface (Strategy Pattern)

Implementations:
- NoOpCache — Null Object (cache disabled by default)
- EntityCacheKey — generates cache keys for entities (e.g., issue:PROJ-123)

Details: src/cache/

Interface:
`typescript
interface CacheManager {
get(key: string): Promise;
set(key: string, value: T, ttl?: number): Promise;
delete(key: string): Promise;
clear(): Promise;
}
`

$3

ParallelExecutor — executes batch operations with concurrency control (using p-limit)

Configuration:
- maxBatchSize (business limit, default: 200)
- maxConcurrentRequests (technical limit, default: 5)

Features:
- ✅ Validates batch size before execution
- ✅ Uses p-limit for concurrency control
- ✅ Logs metrics (success/error counts, duration)
- ✅ Returns typed BatchResult

Implementation: src/async/parallel-executor.ts

Method signature:
`typescript
async executeParallel(
operations: Array<{ key: TKey; fn: () => Promise }>,
operationName?: string
): Promise>
`

$3

Pino logger — production-ready structured logging with rotation

Key features:
- ✅ Structured JSON logs
- ✅ Automatic rotation (daily + size-based → .gz archives)
- ✅ Dual output (errors → stderr + file, info/debug → file only)
- ✅ Child loggers for request tracing

Configuration ENV vars:
- LOGS_DIR, LOG_LEVEL, PRETTY_LOGS, LOG_MAX_SIZE, LOG_MAX_FILES

Full documentation: src/logging/README.md

Function signature:
`typescript
function createLogger(config: LoggerConfig): Logger
`

---

🔄 Migration from v1.x

$3

ServerConfig, loadConfig(), and domain-specific constants have been removed from infrastructure.

Reason: Infrastructure layer must be domain-agnostic.

Migration:
`typescript
// Before (v1.x):
import { ServerConfig, loadConfig } from '@fractalizer/mcp-infrastructure';

// After (v2.0.0):
// For Yandex Tracker server:
import { ServerConfig, loadConfig } from '@fractalizer/mcp-server-yandex-tracker/config';

// For custom servers:
// Implement your own config loader based on your domain requirements
`


---

🚨 Critical Rules

$3

`typescript
// ❌ FORBIDDEN (domain import)
import { Issue } from 'your-domain/entities/issue.js';

// ✅ CORRECT (generic types)
class HttpClient {
async get(url: string): Promise { ... }
}
`

$3

`typescript
// ❌ FORBIDDEN (hardcoded values)
const timeout = 30000;

// ✅ CORRECT (from config)
const timeout = config.requestTimeout;
`

$3

`typescript
// ✅ Retry works automatically
const client = new HttpClient(config, logger, retryHandler);
await client.get('/api/endpoint'); // Auto-retry on error
`

$3

`typescript
// ✅ HttpClient automatically maps AxiosError → ApiError
try {
await client.get('/api/not-found');
} catch (error) {
// error: ApiError (not AxiosError)
console.error(error.statusCode, error.message);
}
`

---

📖 API Reference

$3

`typescript
// HTTP
export { HttpClient } from './http/client/http-client.js';
export { RetryHandler } from './http/retry/retry-handler.js';
export { ExponentialBackoffStrategy } from './http/retry/exponential-backoff.strategy.js';
export { ErrorMapper } from './http/error/error-mapper.js';

// Cache
export type { CacheManager } from './cache/cache-manager.interface.js';
export { NoOpCache } from './cache/no-op-cache.js';
export { EntityCacheKey, EntityType } from './cache/entity-cache-key.js';

// Async
export { ParallelExecutor } from './async/parallel-executor.js';

// Logging
export { createLogger } from './logging/logger.js';

// Types
export type { ApiError, BatchResult, LogLevel } from './types.js';
`

---

🧪 Testing

Run tests:
`bash
cd packages/framework/infrastructure
npm run test
`

With coverage:
`bash
npm run test:coverage
`

Watch mode:
`bash
npm run test:watch
``

---

🤝 Contributing

See ../../.github/CONTRIBUTING.md

Architecture rules: ../../CLAUDE.md

---

📄 License

MIT License

---

🔗 Links

- Monorepo root: ../../README.md
- Architecture: ../../ARCHITECTURE.md