# MCP System Info Server

A simple [Model Context Protocol](https://modelcontextprotocol.io) server that provides system information and public IP lookup tools for Claude Code.

## Features

### Tools

- **`get_public_ip`**: Get your public IP address with geolocation info (country, city, ISP, timezone)
- **`get_system_info`**: Get local system information (OS, CPU, memory, uptime)

### Resources

- **`system://info`**: Static resource with current system information

## Installation

```bash
npm install
npm run build
```

## Usage with Claude Code

### Via CLI (recommended)

```bash
claude mcp add system-info node /path/to/mcp-demo/dist/index.js
```

### Manual configuration

Add to your `~/.claude.json`:

```json
{
  "mcpServers": {
    "system-info": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-demo/dist/index.js"],
      "env": {}
    }
  }
}
```

Reload your IDE/Claude Code, and you can now ask:
- "What's my public IP?"
- "Give me system information"
- "Where am I connected from?"

## How it works

```
┌─────────────┐         JSON-RPC          ┌─────────────┐
│ Claude Code │ ────────────────────────> │  MCP Server │
│  (Client)   │   stdio (stdin/stdout)    │ (this repo) │
│             │ <──────────────────────── │             │
└─────────────┘                          └─────────────┘
                                                 │
                                                 ↓
                                         ┌──────────────┐
                                         │ ipify API    │
                                         │ ip-api.com   │
                                         │ Node.js os   │
                                         └──────────────┘
```

The server implements the MCP protocol to:
1. Expose available tools via `tools/list`
2. Execute tool calls via `tools/call`
3. Expose resources via `resources/list` and `resources/read`

## Development

### Project structure

```
mcp-demo/
├── src/
│   └── index.ts          # MCP server implementation
├── dist/                 # Compiled JavaScript
├── package.json
└── tsconfig.json
```

### Modifying the server

1. Edit `src/index.ts`
2. Run `npm run build`
3. Reload Claude Code (Cmd+Shift+P → "Reload Window")

### Testing manually

```bash
# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

# Call a tool
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_public_ip","arguments":{}}}' | node dist/index.js
```

## Dependencies

- [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk): Official MCP SDK
- [`axios`](https://github.com/axios/axios): HTTP client for API calls
- `os`: Native Node.js module for system info

## Extending

To add a new tool:

1. Add tool definition in `ListToolsRequestSchema` handler
2. Implement tool logic in `CallToolRequestSchema` handler

Example:

```typescript
// 1. Add to tool list
{
  name: "get_weather",
  description: "Get current weather",
  inputSchema: {
    type: "object",
    properties: {
      city: { type: "string" }
    },
    required: ["city"]
  }
}

// 2. Handle the call
if (name === "get_weather") {
  const { city } = request.params.arguments;
  const response = await axios.get(`https://api.weather.com/${city}`);
  return {
    content: [{ type: "text", text: JSON.stringify(response.data) }]
  };
}
```

## License

MIT

## Resources

- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
- [MCP Server Registry](https://github.com/modelcontextprotocol/servers)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)