npm package: @jonmatum/network-mcp-server
Description: Educational POC: MCP server for querying network infrastructure data across global data centers. Not for production use.
Author: Jonatan Mata
Latest version: 1.0.3

# Network MCP Server

> **⚠️ Educational Purpose Only**: This is a proof-of-concept (POC) project designed for learning and demonstration purposes. It is not intended for production use.

A Model Context Protocol (MCP) server that provides network infrastructure data through a simple query interface. This server integrates with Kiro CLI and other MCP clients to extend AI capabilities with custom network infrastructure tools.

## Overview

This MCP server exposes 4 specialized tools that allow querying network infrastructure information across multiple regions, countries, and data centers. It demonstrates how to build and integrate custom MCP servers with Kiro CLI (Amazon Q CLI).

## Features

- **Network Infrastructure Data**: Query routers, switches, and firewalls across global data centers
- **Multiple Tools**: 4 specialized tools for querying, summarizing, searching, and comparing infrastructure
- **Flexible Search**: Search by region, country, or specific site name
- **MCP Protocol**: Built on the Model Context Protocol standard
- **Kiro CLI Integration**: Seamlessly integrates with Kiro CLI (Amazon Q CLI)

## Prerequisites

- Node.js (v18 or higher recommended)
- npm or yarn
- Kiro CLI installed

## Installation

### From npm (Recommended)

```bash
npm install -g @jonmatum/network-mcp-server
```

### From Source

```bash
git clone https://github.com/jonmatum/network-mcp-server.git
cd network-mcp-server
npm install
npm run build
```

## Project Structure

```
network-mcp-server/
├── src/
│   ├── index.ts          # Main server implementation
│   └── network-data.json # Infrastructure data
├── build/
│   ├── index.js          # Compiled JavaScript
│   └── network-data.json # Copied data file
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── LICENSE              # MIT License
└── README.md            # This file
```

## Configuration Files

### tsconfig.json
```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "node",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
```

## Kiro CLI Integration

### 1. Configure MCP Server in Kiro CLI

Edit your Kiro CLI MCP configuration file at `~/.kiro/settings/mcp.json`:

**If installed globally via npm:**
```json
{
  "mcpServers": {
    "network-server": {
      "command": "network-mcp-server",
      "args": []
    }
  }
}
```

**If using npx (no installation required):**
```json
{
  "mcpServers": {
    "network-server": {
      "command": "npx",
      "args": ["@jonmatum/network-mcp-server"]
    }
  }
}
```

**If running from source:**
```json
{
  "mcpServers": {
    "network-server": {
      "command": "node",
      "args": ["/path/to/network-mcp-server/build/index.js"]
    }
  }
}
```

### 2. Verify Configuration

After adding the configuration, restart Kiro CLI or start a new chat session:

```bash
kiro-cli chat
```

### 3. Test the Integration

In Kiro CLI, you can now use the tools:

```
Can you get data for Tokyo?
Can you show me all sites in North America?
What infrastructure do we have in Germany?
Give me a regional summary for Europe
Find all sites with more than 15 routers
Compare Tokyo DC1 and London DC1
```

## Available Tools

### get_data

Retrieves network infrastructure data based on a query string.

**Parameters**:
- `query` (string, required): Search term for region, country, or site name

**Example Queries**:
- "North America" - Returns all North American sites
- "Japan" - Returns all Japanese data centers
- "London" - Returns London DC1 information

**Response Format**:
```json
[
  {
    "region": "Asia Pacific",
    "country": "Japan",
    "sites": [
      {
        "site": "Tokyo DC1",
        "routers": 18,
        "switches": 60,
        "firewalls": 12
      }
    ]
  }
]
```

### get_regional_summary

Get aggregated statistics for a region including total equipment counts and site counts.

**Parameters**:
- `region` (string, required): Region name (e.g., 'North America', 'Europe', 'Asia Pacific')

**Response Format**:
```json
{
  "region": "Europe",
  "totals": {
    "sites": 15,
    "routers": 120,
    "switches": 450,
    "firewalls": 80
  },
  "countries": [
    {
      "country": "UK",
      "sites": 3,
      "routers": 26,
      "switches": 96,
      "firewalls": 17
    }
  ]
}
```

### search_by_equipment

Find sites based on equipment count criteria.

**Parameters**:
- `equipment_type` (string, required): Equipment type: 'routers', 'switches', or 'firewalls'
- `operator` (string, required): Comparison operator: 'greater_than', 'less_than', or 'equals'
- `count` (number, required): Equipment count to compare against

**Example**: Find all sites with more than 15 routers

**Response Format**:
```json
[
  {
    "region": "Europe",
    "country": "Germany",
    "site": "Frankfurt DC1",
    "routers": 16,
    "switches": 55,
    "firewalls": 11
  }
]
```

### compare_sites

Compare infrastructure between multiple sites.

**Parameters**:
- `sites` (array, required): Array of site names to compare

**Example**: Compare "Tokyo DC1" and "London DC1"

**Response Format**:
```json
[
  {
    "region": "Asia Pacific",
    "country": "Japan",
    "site": "Tokyo DC1",
    "routers": 18,
    "switches": 60,
    "firewalls": 12
  },
  {
    "region": "Europe",
    "country": "UK",
    "site": "London DC1",
    "routers": 14,
    "switches": 48,
    "firewalls": 9
  }
]
```

## Data Coverage

The server includes infrastructure data for:

**North America**:
- USA: New York, Chicago, San Francisco, Dallas, Seattle
- Canada: Toronto, Vancouver, Montreal
- Mexico: Mexico City, Monterrey

**Europe**:
- UK: London, Manchester, Edinburgh
- Germany: Frankfurt, Berlin, Munich
- France: Paris, Marseille
- Netherlands: Amsterdam, Rotterdam
- Spain: Madrid, Barcelona
- Italy: Milan, Rome

**Asia Pacific**:
- Japan: Tokyo, Osaka, Nagoya
- Singapore: Singapore DC1, Singapore DC2
- Australia: Sydney, Melbourne, Brisbane
- South Korea: Seoul, Busan
- India: Mumbai, Bangalore, Delhi
- Hong Kong: Hong Kong DC1

**South America**:
- Brazil: São Paulo, Rio de Janeiro, Brasília
- Argentina: Buenos Aires, Córdoba
- Chile: Santiago
- Colombia: Bogotá

**Middle East**:
- UAE: Dubai, Abu Dhabi
- Saudi Arabia: Riyadh, Jeddah
- Israel: Tel Aviv

**Africa**:
- South Africa: Johannesburg, Cape Town
- Nigeria: Lagos
- Kenya: Nairobi

## Development

### Run in Development Mode

```bash
npm run dev
```

This uses `tsx` to run TypeScript directly without compilation.

### Build for Production

```bash
npm run build
```

Compiles TypeScript to JavaScript in the `build/` directory.

### Start the Server

```bash
npm start
```

Runs the compiled JavaScript server.

## Troubleshooting

### Server Not Appearing in Kiro CLI

1. Check that the path in `mcp.json` is absolute and correct
2. Verify the server builds successfully: `npm run build`
3. Test the server manually: `node build/index.js`
4. Restart Kiro CLI

### Build Errors

1. Ensure all dependencies are installed: `npm install`
2. Check Node.js version: `node --version` (should be v18+)
3. Verify TypeScript configuration in `tsconfig.json`

### Tool Not Working

1. Check Kiro CLI logs for errors
2. Verify the tool name matches exactly: `get_data`
3. Ensure query parameter is a string

## Extending the Server

### Important: Shebang Line

The `src/index.ts` file must start with the shebang line for the executable to work when installed via npm:

```typescript
#!/usr/bin/env node
```

This is required for the `bin` configuration in `package.json` to function correctly.

### Adding New Tools

1. Add tool definition in `ListToolsRequestSchema` handler:
```typescript
{
  name: "new_tool",
  description: "Description of new tool",
  inputSchema: {
    type: "object",
    properties: {
      param: { type: "string", description: "Parameter description" }
    },
    required: ["param"]
  }
}
```

2. Add tool handler in `CallToolRequestSchema`:
```typescript
if (request.params.name === "new_tool") {
  // Tool implementation
  return {
    content: [{ type: "text", text: "Result" }]
  };
}
```

3. Rebuild: `npm run build`

### Adding More Data

Edit `src/network-data.json` to add additional regions, countries, or sites following the existing structure.

## MCP Protocol Resources

- [MCP Specification](https://modelcontextprotocol.io/)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk)
- [Amazon Q CLI Documentation](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line.html)

## License

MIT - See [LICENSE](LICENSE) file for details

## Author

Jonatan Mata ([@jonmatum](https://github.com/jonmatum))

## Contributing

1. Fork the repository: https://github.com/jonmatum/network-mcp-server
2. Create a feature branch
3. Make your changes
4. Test with Kiro CLI or Claude Desktop
5. Submit a pull request

## Support

For issues or questions:
- Open an issue: https://github.com/jonmatum/network-mcp-server/issues
- Check the troubleshooting section
- Review MCP protocol documentation