@pipeworx/mcp-ipaddress 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pipeworx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# mcp-ipaddress
+
+IP address utilities MCP.
+
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1170+ live data sources.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `parse_ip` | Validate and classify an IP address (IPv4 or IPv6): version, validity, and classification (private/loopback/link-local/multicast/reserved/public). IPv4 also returns its 32-bit integer. Keyless, offline. |
+| `cidr_info` | Parse an IPv4 CIDR block (e.g. "192.168.1.0/24") and compute the network address, broadcast, netmask, wildcard, usable host range and host count. Keyless, offline. |
+
+## Quick Start
+
+Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
+
+```json
+{
+  "mcpServers": {
+    "ipaddress": {
+      "url": "https://gateway.pipeworx.io/ipaddress/mcp"
+    }
+  }
+}
+```
+
+Or connect to the full Pipeworx gateway for access to all 1170+ data sources:
+
+```json
+{
+  "mcpServers": {
+    "pipeworx": {
+      "url": "https://gateway.pipeworx.io/mcp"
+    }
+  }
+}
+```
+
+## Using with ask_pipeworx
+
+Instead of calling tools directly, you can ask questions in plain English:
+
+```
+ask_pipeworx({ question: "your question about Ipaddress data" })
+```
+
+The gateway picks the right tool and fills the arguments automatically.
+
+## More
+
+- [All tools and guides](https://github.com/pipeworx-io/examples)
+- [pipeworx.io](https://pipeworx.io)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@pipeworx/mcp-ipaddress",
+  "version": "0.1.0",
+  "description": "IP address utilities MCP.",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "ipaddress"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pipeworx-io/mcp-ipaddress"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}

package/server.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.pipeworx-io/ipaddress",
+  "title": "Ipaddress",
+  "description": "IP address utilities MCP.",
+  "version": "0.1.0",
+  "websiteUrl": "https://pipeworx.io/packs/ipaddress",
+  "repository": {
+    "url": "https://github.com/pipeworx-io/mcp-ipaddress",
+    "source": "github"
+  },
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://gateway.pipeworx.io/ipaddress/mcp"
+    }
+  ]
+}

package/src/index.ts

@@ -0,0 +1,119 @@
+interface McpToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+interface McpToolExport {
+  tools: McpToolDefinition[];
+  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+  meter?: { credits: number };
+  cost?: Record<string, unknown>;
+  provider?: string;
+}
+
+/**
+ * IP address utilities MCP.
+ *
+ * Keyless, offline: validate & classify IPv4/IPv6 addresses (private, loopback,
+ * link-local, multicast, reserved) and compute IPv4 subnet math from CIDR
+ * (network, broadcast, netmask, host range, host count). Pure logic — no API,
+ * no key. (IPv6 is validated & classified; full IPv6 subnet math is out of scope.)
+ */
+
+
+function parseV4(ip: string): number[] | null {
+  const p = ip.split('.');
+  if (p.length !== 4) return null;
+  const o = p.map((x) => (/^\d{1,3}$/.test(x) ? +x : -1));
+  return o.every((n) => n >= 0 && n <= 255) ? o : null;
+}
+const v4int = (o: number[]) => (o[0] * 2 ** 24 + o[1] * 2 ** 16 + o[2] * 2 ** 8 + o[3]) >>> 0;
+const intV4 = (n: number) => [(n >>> 24) & 255, (n >>> 16) & 255, (n >>> 8) & 255, n & 255].join('.');
+
+function classifyV4(o: number[]): string[] {
+  const tags: string[] = [];
+  if (o[0] === 10 || (o[0] === 172 && o[1] >= 16 && o[1] <= 31) || (o[0] === 192 && o[1] === 168)) tags.push('private');
+  if (o[0] === 127) tags.push('loopback');
+  if (o[0] === 169 && o[1] === 254) tags.push('link-local');
+  if (o[0] >= 224 && o[0] <= 239) tags.push('multicast');
+  if (o[0] >= 240) tags.push('reserved');
+  if (o[0] === 0) tags.push('this-network');
+  if (o[0] === 100 && o[1] >= 64 && o[1] <= 127) tags.push('cgnat');
+  if (tags.length === 0) tags.push('public');
+  return tags;
+}
+
+const V6 = /^(([0-9a-f]{1,4}:){7}[0-9a-f]{1,4}|([0-9a-f]{1,4}:){1,7}:|([0-9a-f]{1,4}:){1,6}:[0-9a-f]{1,4}|([0-9a-f]{1,4}:){1,5}(:[0-9a-f]{1,4}){1,2}|([0-9a-f]{1,4}:){1,4}(:[0-9a-f]{1,4}){1,3}|([0-9a-f]{1,4}:){1,3}(:[0-9a-f]{1,4}){1,4}|([0-9a-f]{1,4}:){1,2}(:[0-9a-f]{1,4}){1,5}|[0-9a-f]{1,4}:((:[0-9a-f]{1,4}){1,6})|:((:[0-9a-f]{1,4}){1,7}|:)|::(ffff(:0{1,4})?:)?((25[0-5]|(2[0-4]|1?[0-9])?[0-9])\.){3}(25[0-5]|(2[0-4]|1?[0-9])?[0-9]))$/i;
+function classifyV6(ip: string): string[] {
+  const l = ip.toLowerCase();
+  const tags: string[] = [];
+  if (l === '::1') tags.push('loopback');
+  if (l === '::') tags.push('unspecified');
+  if (/^fe[89ab]/.test(l)) tags.push('link-local');
+  if (/^f[cd]/.test(l)) tags.push('unique-local');
+  if (/^ff/.test(l)) tags.push('multicast');
+  if (/^2001:db8/.test(l)) tags.push('documentation');
+  if (tags.length === 0) tags.push('global-unicast');
+  return tags;
+}
+
+const tools: McpToolExport['tools'] = [
+  {
+    name: 'parse_ip',
+    description: 'Validate and classify an IP address (IPv4 or IPv6): version, validity, and classification (private/loopback/link-local/multicast/reserved/public). IPv4 also returns its 32-bit integer. Keyless, offline.',
+    inputSchema: { type: 'object', properties: { ip: { type: 'string', description: 'An IPv4 or IPv6 address, e.g. "192.168.1.10" or "2001:db8::1".' } }, required: ['ip'] },
+  },
+  {
+    name: 'cidr_info',
+    description: 'Parse an IPv4 CIDR block (e.g. "192.168.1.0/24") and compute the network address, broadcast, netmask, wildcard, usable host range and host count. Keyless, offline.',
+    inputSchema: { type: 'object', properties: { cidr: { type: 'string', description: 'An IPv4 CIDR, e.g. "10.0.0.0/8".' } }, required: ['cidr'] },
+  },
+];
+
+async function callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+  switch (name) {
+    case 'parse_ip': {
+      const ip = reqStr(args, 'ip', '"192.168.1.10"').trim();
+      const o = parseV4(ip);
+      if (o) return { input: ip, valid: true, version: 4, integer: v4int(o), classification: classifyV4(o) };
+      if (V6.test(ip)) return { input: ip, valid: true, version: 6, classification: classifyV6(ip) };
+      return { input: ip, valid: false, reason: 'Not a valid IPv4 or IPv6 address.' };
+    }
+    case 'cidr_info': {
+      const cidr = reqStr(args, 'cidr', '"192.168.1.0/24"').trim();
+      const [ipStr, prefStr] = cidr.split('/');
+      const o = parseV4(ipStr || '');
+      const prefix = /^\d{1,2}$/.test(prefStr || '') ? +prefStr : -1;
+      if (!o || prefix < 0 || prefix > 32) return { input: cidr, valid: false, reason: 'Expected an IPv4 CIDR like "192.168.1.0/24" (prefix 0-32).' };
+      const ipn = v4int(o);
+      const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+      const network = (ipn & mask) >>> 0;
+      const broadcast = (network | (~mask >>> 0)) >>> 0;
+      const total = 2 ** (32 - prefix);
+      const usable = prefix >= 31 ? total : total - 2;
+      return {
+        input: cidr, valid: true, prefix,
+        network: intV4(network), broadcast: intV4(broadcast),
+        netmask: intV4(mask), wildcard: intV4(~mask >>> 0),
+        first_host: prefix >= 31 ? intV4(network) : intV4((network + 1) >>> 0),
+        last_host: prefix >= 31 ? intV4(broadcast) : intV4((broadcast - 1) >>> 0),
+        total_addresses: total, usable_hosts: usable,
+      };
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+function reqStr(args: Record<string, unknown>, key: string, ex: string): string {
+  const v = args[key];
+  if (typeof v !== 'string' || !v.trim()) throw new Error(`Required argument "${key}" is missing. Pass a string like ${ex}.`);
+  return v;
+}
+
+export default { tools, callTool, meter: { credits: 1 } } satisfies McpToolExport;

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true
+  },
+  "include": ["src"]
+}