# MCP Server Hub

A production-ready MCP (Model Context Protocol) server suite for AI agent tool integration.
Provides five composable tool modules — code analysis, web scraping, file operations, API
integration, and data transformation — accessible via any MCP-compatible client.

```text
                    ┌─────────────────────────────────────┐
                    │          MCP Client (AI Agent)       │
                    │  (Claude Code, Cursor, VS Code, etc) │
                    └───────────────┬─────────────────────┘
                                    │  JSON-RPC over stdio
                                    ▼
              ┌─────────────────────────────────────────┐
              │           MCP Server Hub                │
              │  ┌───────────────────────────────────┐  │
              │  │         Server Core              │  │
              │  │  ┌────────────┬──────────────┐   │  │
              │  │  │ Tool Router│  Validator   │   │  │
              │  │  │ (Zod)      │  (JSON-RPC)  │   │  │
              │  │  └─────┬──────┴──────┬───────┘   │  │
              │  └────────┼─────────────┼────────────┘  │
              │           │             │               │
              │     ┌─────┴─────────────┴──────┐        │
              │     │    Tool Registry         │        │
              │     │  ┌─────┬─────┬─────┬────┴──┐     │
              │     │  │ CA  │ WS  │ FO  │ AI │ DT │     │
              │     │  └──┬──┴──┬──┴──┬──┴──┬──┴──┘     │
              │     └─────┼─────┼─────┼─────┼────────┘   │
              └───────────┼─────┼─────┼─────┼────────────┘
                          │     │     │     │
                  ┌───────┘     │     │     └───────────┐
                  ▼             ▼     ▼                  ▼
          ┌────────────┐ ┌──────────┐ ┌────────┐ ┌──────────────┐
          │ Code       │ │ Web      │ │ File   │ │ API          │
          │ Analyzer   │ │ Scraper  │ │ Ops    │ │ Integration  │
          └────────────┘ └──────────┘ └────────┘ └──────────────┘

                                          ┌────────────────────┐
                                          │ Data Transformer   │
                                          │ JSON / CSV / YAML  │
                                          └────────────────────┘

Legend: CA=CodeAnalyzer  WS=WebScraper  FO=FileOperations
        AI=ApiIntegration  DT=DataTransformer
```

## Architecture

The server implements the **Model Context Protocol** using the official
`@modelcontextprotocol/sdk`. Communication happens over **stdio** using
**JSON-RPC 2.0** message format.

### Layers

| Layer | Description |
|-------|-------------|
| **Transport** | StdioServerTransport — stdin/stdout JSON-RPC |
| **Server Core** | Request routing, lifecycle, error boundaries |
| **Tool Registry** | Tool definitions, Zod validation, handler dispatch |
| **Tool Modules** | Five isolated domain modules with single responsibility |
| **Logger** | Structured console logging with severity levels |

### Tool Modules

| Tool | Description | Input |
|------|-------------|-------|
| `analyze_code` | JS/TS source analysis — issues, complexity, metrics, patterns | Source code string, language, analysis type |
| `scrape_webpage` | Web content extraction — text, headings, links, metadata | URL, extraction options |
| `execute_file_operations` | File system ops — read, write, delete, list, search | Operations array, root directory |
| `call_api` | HTTP requests — any method, headers, params, body | URL, method, headers, body |
| `transform_data` | Data format conversion — JSON, CSV, YAML with validation | Input string, source/target formats, schema |

## Tech Stack

- **Runtime:** Node.js ≥18
- **Language:** TypeScript 5.4+ (strict mode)
- **Protocol:** MCP SDK `@modelcontextprotocol/sdk` (open source)
- **Validation:** Zod 3.23+
- **HTTP:** Axios 1.7+
- **Data:** `js-yaml`, `csv-parse`, `csv-stringify`

## Installation

```bash
# Clone
git clone https://github.com/your-org/mcp-server-hub.git
cd mcp-server-hub

# Install dependencies
npm install

# Build
npm run build

# Start
npm start
```

### Development

```bash
# Watch mode
npm run dev

# Type check only
npm run lint

# Inspect with MCP Inspector
npm run inspect
```

## Usage

### As a standalone server

```bash
npm start
```

The server listens on **stdin/stdout** and accepts JSON-RPC 2.0 messages.

### Example: List tools

```json
{"jsonrpc":"2.0","id":1,"method":"tools/list"}
```

### Example: Call analyze_code

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "analyze_code",
    "arguments": {
      "code": "function add(a,b){return a+b}",
      "language": "typescript"
    }
  }
}
```

### Integration with AI Agents

This server works with any MCP-compatible client:

- **Claude Code:** Add to `~/.claude/settings.json`
- **Cursor:** Add to Cursor MCP settings
- **Custom agents:** Connect via `child_process` with stdio transport

#### Claude Code configuration

```json
{
  "mcpServers": {
    "mcp-server-hub": {
      "command": "node",
      "args": ["path/to/mcp-server-hub/dist/index.js"]
    }
  }
}
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | 3000 | Server port (reserved) |
| `NODE_ENV` | development | Environment mode |
| `LOG_LEVEL` | info | Logging level (debug/info/warn/error) |
| `SCRAPER_USER_AGENT` | MCP-Server-Hub/1.0 | User agent for web scraping |
| `SCRAPER_TIMEOUT_MS` | 10000 | Scraper request timeout |
| `API_DEFAULT_TIMEOUT_MS` | 15000 | API request timeout |

## Security

- File operations enforce **path traversal protection** — all paths are resolved
  relative to a configurable root directory
- API responses **redact sensitive headers** (Authorization, Cookie, API keys)
- All inputs validated through **Zod schemas** before reaching handlers
- Web scraper respects **max redirects** and **status code** boundaries
- No secrets hardcoded — use `.env` file or environment variables

## Project Structure

```
src/
├── index.ts                   # Server entry, tool routing, MCP init
├── types.ts                   # All TypeScript type definitions
├── logger.ts                  # Structured logging utility
└── tools/
    ├── validation.ts          # Zod schemas for all tool inputs
    ├── code-analyzer.ts       # Code analysis tool module
    ├── web-scraper.ts         # Web scraping tool module
    ├── file-operations.ts     # File operations tool module
    ├── api-integration.ts     # API integration tool module
    └── data-transformer.ts    # Data transformation tool module
```

## License

MIT — see [LICENSE](LICENSE).

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit (`git commit -m 'feat: add amazing feature'`)
4. Push (`git push origin feature/amazing-feature`)
5. Open a Pull Request