@lionad/port-key-mcp 0.1.6

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2026 Lionad
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# PortKey MCP Server
+
+## Description
+
+[Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for PortKey. It provides tools to map project names to port numbers using keyboard-based letter-to-number mapping and get design philosophy.
+
+## Installation
+
+Install MCP server package:
+
+```shell
+npm install @lionad/port-key-mcp
+```
+
+## Usage
+
+### Running the Server
+
+The PortKey MCP server is designed to be run by an IDE-based MCP client like [Visual Studio Code's Copilot](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode).
+
+```shell
+npx @lionad/port-key-mcp
+```
+
+### Available Tools
+
+The MCP server provides following tools:
+
+- **map-project-name-to-port**: Map a project name to a port number using keyboard-based letter-to-number mapping
+- **get-design-philosophy**: Get design philosophy and background of PortKey
+
+#### map-project-name-to-port
+
+##### Tool Parameters
+
+- `projectName` (string, required): The project name to map to a port number
+- `map` (string, optional): Custom mapping in JSON format (e.g., `{ "1": "qaz", "2": "wsx", ... }`)
+- `preferDigitCount` (number, optional): Preferred digit count for port (2-5, default: 4)
+- `minPort` (number, optional): Minimum port number (0-65535, default: 0)
+- `maxPort` (number, optional): Maximum port number (0-65535, default: 65535)
+- `blockedPorts` (array of numbers, optional): List of blocked port numbers to avoid
+
+##### Example Tool Call
+
+```json
+{
+  "name": "map-project-name-to-port",
+  "arguments": {
+    "projectName": "cfetch",
+    "preferDigitCount": 4
+  }
+}
+```
+
+##### Example Response
+
+```json
+{
+  "digits": "343536",
+  "port": 3435,
+  "rejectedCandidates": []
+}
+```
+
+#### get-design-philosophy
+
+##### Tool Parameters
+
+- `lang` (string, optional): Language code for design philosophy content. Supported languages: `"cn"`, `"es"`, `"fr"`, `"de"`, `"ja"`, `"ko"`, `"ru"`, `"ar"`, `"pt"`, `"it"`. Default: `"cn"`.
+
+##### Example Tool Call
+
+```json
+{
+  "name": "get-design-philosophy",
+  "arguments": {
+    "lang": "en"
+  }
+}
+```
+
+##### Example Response
+
+```
+以下是 PortKey 的设计理念：
+
+## 核心思路
+
+PortKey 基于键盘布局将项目名称映射为数字，使端口号既可读又易记。
+...
+```
+
+##### Supported Languages
+
+| Code | Language   |
+|-------|------------|
+| cn    | 中文        |
+| es    | Español    |
+| fr    | Français    |
+| de    | Deutsch     |
+| ja    | 日本語      |
+| ko    | 한국어       |
+| ru    | Русский     |
+| ar    | العربية     |
+| pt    | Português  |
+| it    | Italiano   |
+
+## Configuration
+
+You can configure MCP server in your MCP client's configuration file (e.g., for VS Code Copilot, configure in your `.copilot/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "port-key": {
+      "command": "npx",
+      "args": ["@lionad/port-key-mcp"]
+    }
+  }
+}
+```
+
+## Development
+
+Build locales (generates from docs/ directory):
+
+```shell
+npm run build:locales
+```
+
+Run tests:
+
+```shell
+npm test
+```
+
+Run tests in watch mode:
+
+```shell
+npm run test:watch
+```

package/bin/port-key-mcp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../dist/mcp-cli.js";

package/dist/mcp-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp-cli.js

@@ -0,0 +1,13 @@
+import { mcpServer } from "./mcp-server.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+function disconnect() {
+    mcpServer.close();
+    process.exitCode = 0;
+}
+await mcpServer.connect(new StdioServerTransport());
+// ! never use console.log in stdio MCP servers, but stderr is safe
+// @see https://modelcontextprotocol.io/docs/develop/build-server#logging-in-mcp-servers-2
+console.error(`PortKey MCP server is running. cwd: ${process.cwd()}`);
+process.on("SIGINT", disconnect);
+process.on("SIGTERM", disconnect);
+//# sourceMappingURL=mcp-cli.js.map

package/dist/mcp-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-cli.js","sourceRoot":"","sources":["../src/mcp-cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,SAAS,UAAU;IAClB,SAAS,CAAC,KAAK,EAAE,CAAC;IAClB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,SAAS,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;AAEpD,mEAAmE;AACnE,0FAA0F;AAC1F,OAAO,CAAC,KAAK,CAAC,uCAAuC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAEtE,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AACjC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC"}

package/dist/mcp-server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+declare const mcpServer: McpServer;
+export { mcpServer };

package/dist/mcp-server.js

@@ -0,0 +1,103 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { mapToPort } from "@lionad/port-key";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const SUPPORTED_LANGUAGES = ["cn", "es", "fr", "de", "ja", "ko", "ru", "ar", "pt", "it"];
+async function loadLocale(lang) {
+    const localePath = join(__dirname, "..", "locales", `${lang}.json`);
+    try {
+        const content = await readFile(localePath, "utf-8");
+        const locale = JSON.parse(content);
+        return locale.designPhilosophy || "";
+    }
+    catch {
+        return "";
+    }
+}
+const mcpServer = new McpServer({
+    name: "PortKey",
+    version: "0.1.5",
+});
+mcpServer.registerTool("map-project-name-to-port", {
+    title: "Map Project Name to Port",
+    description: "Map a project name to a port number using keyboard-based letter-to-number mapping",
+    inputSchema: {
+        projectName: z.string().min(1),
+        map: z.string().optional(),
+        preferDigitCount: z.number().int().min(2).max(5).optional(),
+        minPort: z.number().int().min(0).max(65535).optional(),
+        maxPort: z.number().int().min(0).max(65535).optional(),
+        blockedPorts: z.array(z.number().int().min(0).max(65535)).optional(),
+    },
+}, async ({ projectName, map, preferDigitCount, minPort, maxPort, blockedPorts }) => {
+    try {
+        let customMap = undefined;
+        if (map && map !== "") {
+            customMap = JSON.parse(map);
+        }
+        const options = {
+            preferDigitCount,
+            minPort,
+            maxPort,
+            blockedPorts: blockedPorts ? new Set(blockedPorts) : undefined,
+        };
+        const result = mapToPort(projectName, customMap, options);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error && typeof error === "object" && "message" in error ? String(error.message) : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: errorMessage }),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+mcpServer.registerTool("get-design-philosophy", {
+    title: "Get PortKey Design Philosophy",
+    description: "Get design philosophy and background of PortKey",
+    inputSchema: {
+        lang: z.enum([...SUPPORTED_LANGUAGES]).default("cn"),
+    },
+}, async ({ lang = "cn" }) => {
+    try {
+        const philosophy = await loadLocale(lang);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: philosophy,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error && typeof error === "object" && "message" in error ? String(error.message) : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: errorMessage }),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+export { mcpServer };
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"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"}

package/locales/ar.json

@@ -0,0 +1,3 @@
+{
+  "designPhilosophy": "以下是 PortKey 的设计理念：\n\nإنشاء المنافذ باستخدام خريطة من الحروف إلى الأرقام على لوحة المفاتيح\nعند تشغيل مجموعة من المشاريع محليًا، يصبح اختيار أرقام المنافذ أمرًا مزعجًا.\n- خلال السنوات القليلة الماضية، ظهرت *الكثير* من المشاريع الجديدة. لتجربتها، غالبًا ما تحتاج إلى تشغيلها محليًا—ثم تبدأ المنافذ في التعارض.\n- إذا أردت الحفاظ على استقرار علامات التبويب (أو الإشارات) في المتصفح، يجب ألا يتغير منفذ المشروع باستمرار.\nعلى سبيل المثال، لدي أكثر من عشرة تطبيقات Nuxt على جهازّي. إذا كان كلٌ منها يستخدم المنفذ الافتراضي `3000`، فهذا واضح أنه لن ينجح. لذا وجدت قاعدة بسيطة ومتسقة لتسمية المنافذ بحيث \"تخصص\" منفذًا لكل مشروع.\n[مقال المدونة الأصلي](https://lionad.art/articles/simple-naming-method)\n### الفكرة الأساسية\nبدلاً من اختيار أرقام عشوائية، قم بربط **اسم المشروع بالأرقام بناءً على لوحة المفاتيح**، بحيث يكون المنفذ *قابلًا للقراءة* و*سهل التذكر*.\nطالما أن النتيجة تقع ضمن نطاق المنافذ الصالح (**0–65535**) ولا تصطدم بالمنافذ المحجوزة/النظامية، يمكنك استخدامه مباشرة.\nبشكل أكثر تحديدًا: باستخدام لوحة مفاتيح QWERTY قياسية، اربط كل حرف رقمًا واحدًا بناءً على **موقعه في الصف/العمود**.\nمثال:\n`\"cfetch\"` → `c(3) f(4) e(3) t(5) c(3) h(6)` → `34353`（رقم المنفذ）\nثم يمكنك أخذ أول 4 أرقام (مثلًا `3453`)، أو الاحتفاظ بالمزيد من الأرقام (مثلًا `34353`). كلا الخيارين مقبولان.\nإذا كان المشروع يحتاج إلى عدة منافذ (واجهة أمامية، خلفية، قاعدة بيانات، إلخ)، اختر **أحد الطريقتين** التاليتين:\n1. استخدم بادئة المشروع، ثم أضف لاحقة \"دور\"  \n   - بالنسبة إلى `\"cfetch\"`، خذ `3435` كقاعدة  \n   - الواجهة الأمامية (`fe`، أي `43`) → `34354`  \n   - الخلفية (`server`) → `34352`  \n   - قاعدة البيانات (`mongo`) → `34357`  \n   - … وهكذا\n2. استخدم بادئة المشروع، ثم خصص أدوارًا متسلسلة  \n   - بالنسبة إلى `\"cfetch\"`، خذ `3435` كقاعدة  \n   - الويب → `34351`  \n   - الخلفية → `34352`  \n   - قاعدة البيانات → `34353`  \n   - … وهكذا\n### نطاق المنافذ الصالح\n- يجب أن تكون المنافذ ضمن **0–65535**.\n- للخدمات المخصصة، من الأفضل عادةً استخدام النطاق **1024–49151** (غير محجوز) أو **49152–65535** (خاص/ديناميكي).\n- طالما أن الرقم المحوَّل يبقى تحت الحد، فهو صالِح.\n---"
+}

package/locales/cn.json

@@ -0,0 +1,3 @@
+{
+  "designPhilosophy": "以下是 PortKey 的设计理念：\n\n通过字母到数字的键盘映射生成端口号。\n当你在本地运行多个项目时，选择端口号会变得非常麻烦。\n- 在过去几年里，新项目层出不穷。要真正尝试它们，你往往需要在本地启动它们——于是端口冲突接踵而来。  \n- 如果希望浏览器标签页（或书签）保持稳定，一个项目的端口不应频繁变化。\n例如，我的机器上有十多个 Nuxt 应用。如果它们全部默认使用 `3000`，显然不可行。因此，我想出了一个简单且一致的端口命名规则，以“分配”每个项目对应的端口。\n[源博客文章](https://lionad.art/articles/simple-naming-method)\n### 核心思路\n不使用随机数字，而是将**项目名称映射为键盘上的数字**，从而得到*可读且易记*的端口号。\n只要结果在合法的端口范围（**0–65535**）内且不冲突系统保留端口，即可直接使用。\n更具体地说：使用标准 QWERTY 键盘，将每个字母根据其**行/列位置**映射为单个数字。\n示例：\n`\"cfetch\"` → `c(3) f(4) e(3) t(5) c(3) h(6)` → `34353`（端口号）\n然后可以取前 4 位数字（例如 `3453`），也可以保留更多位数（例如 `34353`）。两者皆可。\n如果一个项目需要多个端口（前端、后端、数据库等），可以采用以下两种方式之一：\n1. 使用项目前缀，再追加“角色后缀”  \n   - 对于 `\"cfetch\"`，取 `3435` 作为基数  \n   - 前端（`fe`，即 `43`） → `34354`  \n   - 后端（`server`） → `34352`  \n   - 数据库（`mongo`） → `34357`  \n   - …以此类推  \n2. 使用项目前缀，再按顺序分配角色  \n   - 对于 `\"cfetch\"`，取 `3435` 作为基数  \n   - Web → `34351`  \n   - 后端 → `34352`  \n   - 数据库 → `34353`  \n   - …以此类推  \n### 合法端口范围\n- 端口号必须在 **0–65535** 范围内。  \n- 对于自定义服务，通常最好使用 **1024–49151**（非保留）或 **49152–65535**（私有/动态）范围。  \n- 只要映射得到的数字不超过上限，即为合法。\n---"
+}

package/locales/de.json

@@ -0,0 +1,3 @@
+{
+  "designPhilosophy": "以下是 PortKey 的设计理念：\n\nPorts anhand einer Buchstaben‑zu‑Zahl‑Tastaturzuordnung generieren  \nWenn Sie mehrere Projekte lokal ausführen, wird die Auswahl von Port‑Nummern schnell lästig.\n- In den letzten Jahren sind *so viele* neue Projekte entstanden. Um sie wirklich auszuprobieren, starten Sie sie häufig lokal – und dann kollidieren die Ports.\n- Wenn Sie Browser‑Tabs (oder Lesezeichen) stabil halten wollen, sollte sich der Port eines Projekts nicht ständig ändern.\nZum Beispiel habe ich mehr als zehn Nuxt‑Apps auf meinem Rechner. Wenn sie alle standardmäßig `3000` verwenden würden, würde das natürlich nicht funktionieren. Deshalb habe ich eine einfache, konsistente Port‑Benennungsregel entwickelt, um „Ports“ pro Projekt zuzuordnen.\n[Quell‑Blog‑Beitrag](https://lionad.art/articles/simple-naming-method)\n### Kernidee\nAnstatt zufällige Zahlen zu wählen, wird der **Projektname auf Basis einer Tastaturzuordnung in Ziffern übersetzt**, sodass der Port *lesbar* und *einprägsam* ist.\nSolange das Ergebnis im gültigen Portbereich (**0–65535**) liegt und keine reservierten/System‑Ports trifft, können Sie es verwenden.\nGenauer gesagt: Verwenden Sie eine Standard‑QWERTY‑Tastatur und ordnen Sie jedem Buchstaben anhand seiner **Zeilen-/Spaltenposition** eine einzelne Ziffer zu.\nBeispiel:\n`\"cfetch\"` → `c(3) f(4) e(3) t(5) c(3) h(6)` → `34353`（Port‑Nummer）\nSie können dann die ersten 4 Ziffern (z. B. `3453`) verwenden oder mehr Ziffern behalten (z. B. `34353`). Beides ist in Ordnung.\nFalls ein Projekt mehrere Ports benötigt (Frontend, Backend, Datenbank usw.), wählen Sie **einen** der beiden Ansätze:\n1. Verwenden Sie das Projekt‑Präfix und hängen Sie ein „Rollen‑Suffix“ an  \n   - Für `\"cfetch\"`: Basis = `3435`  \n   - Frontend (`fe`, also `43`) → `34354`  \n   - Backend (`server`) → `34352`  \n   - Datenbank (`mongo`) → `34357`  \n   - …usw.\n2. Verwenden Sie das Projekt‑Präfix und ordnen Sie Rollen sequenziell zu  \n   - Für `\"cfetch\"`: Basis = `3435`  \n   - Web → `34351`  \n   - Backend → `34352`  \n   - Datenbank → `34353`  \n   - …usw.\n### Gültiger Portbereich\n- Ports müssen im Bereich **0–65535** liegen.\n- Für benutzerdefinierte Dienste ist es meist am besten, **1024–49151** (nicht reserviert) oder **49152–65535** (privat/dynamisch) zu verwenden.\n- Solange die abgebildete Zahl unter dem Limit bleibt, ist sie gültig.\n---"
+}

package/locales/es.json

@@ -0,0 +1,3 @@
+{
+  "designPhilosophy": "以下是 PortKey 的设计理念：\n\nGenerar puertos mediante un mapeo de tecla‑letra a número.\nCuando manejas varios proyectos localmente, elegir números de puerto puede resultar molesto.\n- En los últimos años han surgido *muchísimos* proyectos nuevos. Para probarlos, a menudo necesitas iniciarlos localmente y los puertos empiezan a colisionar.\n- Si deseas que las pestañas del navegador (o marcadores) permanezcan estables, el puerto de un proyecto no debería cambiar constantemente.\nPor ejemplo, tengo más de diez aplicaciones Nuxt en mi máquina. Si todas usan por defecto `3000`, obviamente no funcionará. Por eso ideé una regla simple y consistente para “asignar” puertos a cada proyecto.\n[Publicación del blog original](https://lionad.art/articles/simple-naming-method)\n### Idea central\nEn lugar de elegir números aleatorios, asigna **el nombre del proyecto a números según la disposición del teclado**, de modo que el puerto sea *legible* y *memorable*.\nMientras el resultado esté dentro del rango de puertos válido (**0–65535**) y no colisione con puertos reservados/sistema, puedes usarlo directamente.\nMás concretamente: usando un teclado QWERTY estándar, asigna a cada letra un solo dígito según su **posición de fila/columna**.\nEjemplo:\n`\"cfetch\"` → `c(3) f(4) e(3) t(5) c(3) h(6)` → `34353`（número de puerto）\nLuego puedes tomar los primeros 4 dígitos (p. ej., `3453`) o conservar más dígitos (p. ej., `34353`). Cualquiera está bien.\nSi un proyecto necesita varios puertos (frontend, backend, base de datos, etc.), elige **una** de estas dos estrategias:\n1. Usa el prefijo del proyecto y añade un “sufijo de rol”  \n   - Para `\"cfetch\"`, toma `3435` como base  \n   - Frontend (`fe`, es decir, `43`) → `34354`  \n   - Backend (`server`) → `34352`  \n   - Base de datos (`mongo`) → `34357`  \n   - …y así sucesivamente\n2. Usa el prefijo del proyecto y asigna roles secuencialmente  \n   - Para `\"cfetch\"`, toma `3435` como base  \n   - Web → `34351`  \n   - Backend → `34352`  \n   - Base de datos → `34353`  \n   - …y así sucesivamente\n### Rango de puertos válido\n- Los puertos deben estar entre **0–65535**.\n- Para servicios personalizados, suele ser mejor usar el rango **1024–49151** (no reservado) o **49152–65535** (privado/dinámico).\n- Mientras el número mapeado no supere el límite, es válido.\n---"
+}

package/locales/fr.json

@@ -0,0 +1,3 @@
+{
+  "designPhilosophy": "以下是 PortKey 的设计理念：\n\nGénérer des ports grâce à une correspondance clavier lettre‑chiffre.\nLorsque vous exécutez plusieurs projets localement, choisir des numéros de port devient pénible.\n- Au cours des dernières années, il y a eu *tant* de nouveaux projets. Pour les tester réellement, vous devez souvent les lancer localement — et alors les ports commencent à se chevaucher.\n- Si vous voulez que les onglets du navigateur (ou vos signets) restent stables, le port d’un projet ne doit pas changer constamment.\nPar exemple, j’ai plus de dix applications Nuxt sur ma machine. Si elles utilisent toutes le port par défaut `3000`, cela ne fonctionnera évidemment pas. J’ai donc imaginé une règle simple et cohérente de nomination des ports pour « attribuer » un port à chaque projet.\n[Article du blog source](https://lionad.art/articles/simple-naming-method)\n### Idée principale\nAu lieu de choisir des nombres aléatoires, mapper le **nom du projet à des chiffres selon le clavier**, de sorte que le port soit *lisible* et *mémorisable*.\nTant que le résultat reste dans la plage de ports valide (**0–65535**) et n’empiète pas sur les ports réservés/systèmes, vous pouvez l’utiliser tel quel.\nPlus précisément : en se basant sur un clavier QWERTY standard, chaque lettre est associée à un seul chiffre selon sa **position ligne/colonne**.\nExemple :\n`\"cfetch\"` → `c(3) f(4) e(3) t(5) c(3) h(6)` → `34353`（numéro de port）\nVous pouvez alors prendre les 4 premiers chiffres (par ex. `3453`), ou conserver plus de chiffres (par ex. `34353`). Les deux options sont valables.\nSi un projet nécessite plusieurs ports (frontend, backend, base de données, etc.), choisissez **l’une** des deux approches :\n1. Utiliser le préfixe du projet, puis ajouter un « suffixe de rôle »  \n   - Pour `\"cfetch\"`, prendre `3435` comme base  \n   - Frontend (`fe`, c’est‑à‑dire `43`) → `34354`  \n   - Backend (`server`) → `34352`  \n   - Base de données (`mongo`) → `34357`  \n   - …etc.\n2. Utiliser le préfixe du projet, puis attribuer des rôles séquentiels  \n   - Pour `\"cfetch\"`, prendre `3435` comme base  \n   - Web → `34351`  \n   - Backend → `34352`  \n   - Base de données → `34353`  \n   - …etc.\n### Plage de ports valide\n- Les ports doivent être compris entre **0 et 65535**.\n- Pour les services personnalisés, il est généralement préférable d’utiliser la plage **1024–49151** (non réservée) ou **49152–65535** (privé/dynamique).\n- Tant que le nombre mappé reste en dessous de la limite, il est valide.\n---"
+}

package/locales/it.json

@@ -0,0 +1,3 @@
+{
+  "designPhilosophy": "以下是 PortKey 的设计理念：\n\nGenera porte mediante una mappatura da lettere a numeri della tastiera.\nQuando gestisci diversi progetti localmente, scegliere i numeri di porta può diventare un vero fastidio.\n- Negli ultimi anni sono comparsi *tanti* nuovi progetti. Per provarli realmente, spesso è necessario avviarli in locale—e allora le porte cominciano a sovrapporsi.\n- Se vuoi mantenere stabile la barra degli indirizzi del browser (o i segnalibri), la porta di un progetto non dovrebbe cambiare continuamente.\nAd esempio, ho più di dieci applicazioni Nuxt sulla mia macchina. Se tutte usassero la porta predefinita `3000`, chiaramente non funzionerebbe. Perciò ho ideato una regola semplice e coerente per “assegnare” porte a ciascun progetto.\n[Articolo del blog originale](https://lionad.art/articles/simple-naming-method)\n### Idea principale\nInvece di scegliere numeri a caso, mappa il **nome del progetto a numeri basati sulla tastiera**, così la porta risulta *leggibile* e *memorizzabile*.\nFinché il risultato è compreso nell’intervallo valido delle porte (**0–65535**) e non coincide con porte riservate o di sistema, può essere usato direttamente.\nPiù precisamente: usando una tastiera QWERTY standard, associa ogni lettera a una singola cifra in base alla sua **posizione di riga/colonna**.\nEsempio:\n`\"cfetch\"` → `c(3) f(4) e(3) t(5) c(3) h(6)` → `34353`（numero di porta）\nPuoi prendere le prime 4 cifre (ad es. `3453`) o mantenere più cifre (ad es. `34353`). Entrambe le opzioni vanno bene.\nSe un progetto richiede più porte (frontend, backend, database, ecc.), scegli **uno** di questi due approcci:\n1. Usa il prefisso del progetto, quindi aggiungi un “suffisso di ruolo”  \n   - Per `\"cfetch\"`, prendi `3435` come base  \n   - Frontend (`fe`, cioè `43`) → `34354`  \n   - Backend (`server`) → `34352`  \n   - Database (`mongo`) → `34357`  \n   - …e così via\n2. Usa il prefisso del progetto, quindi assegna ruoli sequenziali  \n   - Per `\"cfetch\"`, prendi `3435` come base  \n   - Web → `34351`  \n   - Backend → `34352`  \n   - Database → `34353`  \n   - …e così via\n### Intervallo di porte valido\n- Le porte devono trovarsi nell’intervallo **0–65535**.\n- Per servizi personalizzati, di solito è meglio usare **1024–49151** (non riservate) o **49152–65535** (private/dynamic).\n- Finché il numero mappato rimane sotto il limite, è considerato valido.\n---"
+}

package/locales/ja.json

@@ -0,0 +1,3 @@
+{
+  "designPhilosophy": "以下是 PortKey 的设计理念：\n\nキー入力の文字と数字を対応させてポート番号を生成します。\nローカルで多数のプロジェクトを同時に動かすと、ポート番号の選択が面倒になります。\n- 最近数年で新しいプロジェクトが**大量に**誕生しました。実際に試すにはローカルで起動する必要がありますが、するとポート番号が衝突しやすくなります。  \n- ブラウザのタブやブックマークを安定させたい場合、プロジェクトごとのポートが頻繁に変わっては困ります。\nたとえば、私のマシンには 10 個以上の Nuxt アプリがあります。すべてがデフォルトで `3000` を使用していたら、当然動作しません。そこで私は「プロジェクトごとにポートを割り当てる」シンプルで一貫した命名規則を考案しました。\n[元記事](https://lionad.art/articles/simple-naming-method)\n### 基本コンセプト\nランダムな数字を選ぶのではなく、**キーボード上の位置に基づいてプロジェクト名を数字列に変換**し、ポート番号を *読みやすく* かつ *覚えやすく* します。\n変換結果が有効なポート範囲（**0〜65535**）に収まっていて、予約済み／システムポートと衝突しなければそのまま使用できます。\n具体例（標準 QWERTY キーボードを想定）：\n`\"cfetch\"` → `c(3) f(4) e(3) t(5) c(3) h(6)` → `34353`（ポート番号）\nこのうち先頭 4 桁（例：`3453`）だけ使用するか、5 桁すべて（例：`34353`）を使用しても構いません。\nプロジェクトが複数のポート（フロントエンド、バックエンド、データベース等）を必要とする場合は、次の 2 つの方法のいずれかで「役割」ポートを決めます。\n1. **プロジェクト接頭語＋ロールサフィックス**  \n   - `\"cfetch\"` のベースは `3435`  \n   - フロントエンド（`fe` → `43`） → `34354`  \n   - バックエンド（`server`） → `34352`  \n   - データベース（`mongo`） → `34357`  \n2. **プロジェクト接頭語＋連番ロール**  \n   - `\"cfetch\"` のベースは `3435`  \n   - Web → `34351`  \n   - Backend → `34352`  \n   - Database → `34353`\n### 有効なポート範囲\n- ポート番号は **0〜65535** の範囲内でなければなりません。  \n- カスタムサービスの場合、通常は **1024〜49151**（非予約）または **49152〜65535**（プライベート／動的）の範囲が推奨されます。  \n- マッピング結果が上限未満であれば有効です。\n---"
+}

package/locales/ko.json

@@ -0,0 +1,3 @@
+{
+  "designPhilosophy": "以下是 PortKey 的设计理念：\n\n키보드의 문자-숫자 매핑을 이용해 포트를 생성합니다.\n여러 프로젝트를 로컬에서 실행할 때, 포트 번호 선택이 번거로울 수 있습니다.\n- 최근 몇 년간 새로운 프로젝트가 *매우 많이* 생겨났습니다. 실제로 사용해 보려면 로컬에서 부팅해야 하는 경우가 많고, 이때 포트 충돌이 발생합니다.\n- 브라우저 탭(또는 북마크)을 안정적으로 유지하려면, 프로젝트마다 포트가 계속 바뀌지 않아야 합니다.\n예를 들어, 제 컴퓨터에는 Nuxt 애플리케이션이 10개 이상 있습니다. 모두가 기본값인 `3000`을 사용한다면 당연히 충돌이 발생합니다. 그래서 저는 프로젝트마다 “포트를 할당”하는 간단하고 일관된 규칙을 고안했습니다.\n[Source Blog Post](https://lionad.art/articles/simple-naming-method)\n### 핵심 아이디어\n임의의 숫자를 선택하는 대신, **키보드 레이아웃을 기준으로 프로젝트명을 숫자로 매핑**합니다. 이렇게 하면 포트 번호가 *읽기 쉽고* *외우기 쉬운* 형태가 됩니다.\n결과가 유효한 포트 범위(**0–65535**) 안에 들어가고, 예약/시스템 포트를 피한다면 그대로 사용할 수 있습니다.\n구체적으로는 QWERTY 키보드의 각 문자 위치를 기준으로, **행/열**에 따라 하나의 숫자로 매핑합니다.\n예시:\n`\"cfetch\"` → `c(3) f(4) e(3) t(5) c(3) h(6)` → `34353`（포트 번호）\n그 후 처음 4자리(`3453`)를 사용하거나, 전체 5자리를 그대로 사용할 수 있습니다. 두 방법 모두 괜찮습니다.\n프로젝트에 여러 포트가 필요할 경우(프론트엔드, 백엔드, 데이터베이스 등), 다음 두 가지 방법 중 하나를 선택합니다:\n1. 프로젝트 접두사 뒤에 **역할 접미사**를 붙인다  \n   - `\"cfetch\"`의 경우 기본값 `3435`를 사용  \n   - 프론트엔드(`fe`, 즉 `43`) → `34354`  \n   - 백엔드(`server`) → `34352`  \n   - 데이터베이스(`mongo`) → `34357`  \n2. 프로젝트 접두사 뒤에 **순차적인 역할 번호**를 부여한다  \n   - `\"cfetch\"`의 경우 기본값 `3435`를 사용  \n   - 웹 → `34351`  \n   - 백엔드 → `34352`  \n   - 데이터베이스 → `34353`\n### 유효 포트 범위\n- 포트 번호는 **0–65535** 사이여야 합니다.\n- 사용자 정의 서비스의 경우 일반적으로 **1024–49151**(비예약) 혹은 **49152–65535**(프라이빗/동적) 범위를 사용하는 것이 좋습니다.\n- 매핑된 숫자가 이 제한 이하라면 유효합니다.\n---"
+}

package/locales/pt.json

@@ -0,0 +1,3 @@
+{
+  "designPhilosophy": "以下是 PortKey 的设计理念：\n\nGerar portas usando um mapeamento de letras para números baseado no teclado.\nQuando você está executando vários projetos localmente, escolher números de porta pode ser complicado.\n- Nos últimos anos surgiram *tantos* novos projetos. Para realmente testá‑los, muitas vezes você precisa iniciá‑los localmente — e então as portas começam a colidir.\n- Se quiser manter as guias do navegador (ou favoritos) estáveis, a porta de um projeto não deve mudar constantemente.\nPor exemplo, eu tenho mais de dez aplicativos Nuxt na minha máquina. Se todos eles usarem a porta padrão `3000`, obviamente não vai funcionar. Por isso criei uma regra simples e consistente de nomeação de portas para “atribuir” portas por projeto.\n[Postagem original no blog](https://lionad.art/articles/simple-naming-method)\n### Ideia principal\nEm vez de escolher números aleatórios, mapeie o **nome do projeto para números com base no teclado**, de modo que a porta seja *legível* e *memorizável*.\nDesde que o resultado esteja dentro da faixa válida de portas (**0–65535**) e não colida com portas reservadas/sistema, ele pode ser usado diretamente.\nMais especificamente: usando um teclado QWERTY padrão, associe cada letra a um único dígito de acordo com sua **posição na linha/coluna**.\nExemplo:\n`\"cfetch\"` → `c(3) f(4) e(3) t(5) c(3) h(6)` → `34353`（número da porta）\nEntão você pode usar os primeiros 4 dígitos (por exemplo `3453`) ou manter mais dígitos (por exemplo `34353`). Ambos são válidos.\nSe um projeto precisar de várias portas (frontend, backend, banco de dados etc.), escolha **uma** das duas abordagens a seguir:\n1. Use o prefixo do projeto e, em seguida, adicione um “sufixo de função”  \n   - Para `\"cfetch\"`, tome `3435` como base  \n   - Frontend (`fe`, ou seja, `43`) → `34354`  \n   - Backend (`server`) → `34352`  \n   - Banco de dados (`mongo`) → `34357`  \n   - …e assim por diante\n2. Use o prefixo do projeto e, então, atribua funções sequencialmente  \n   - Para `\"cfetch\"`, tome `3435` como base  \n   - Web → `34351`  \n   - Backend → `34352`  \n   - Banco de dados → `34353`  \n   - …e assim por diante\n### Faixa válida de portas\n- As portas devem estar entre **0–65535**.  \n- Para serviços personalizados, costuma ser melhor usar a faixa **1024–49151** (não reservada) ou **49152–65535** (privada/dinâmica).  \n- Desde que o número mapeado fique dentro do limite, ele é válido.\n---"
+}

package/locales/ru.json

@@ -0,0 +1,3 @@
+{
+  "designPhilosophy": "以下是 PortKey 的设计理念：\n\nГенерация портов с помощью сопоставления букв клавиатуры с цифрами.\nКогда вы запускаете несколько проектов локально, выбор номеров портов становится раздражающим.\n- За последние пару лет появилось *так много* новых проектов. Чтобы действительно их протестировать, часто нужно запустить их локально — и тогда порты начинают конфликтовать.\n- Если вы хотите, чтобы вкладки браузера (или закладки) оставались стабильными, порт проекта не должен постоянно меняться.\nНапример, у меня на машине более десяти приложений Nuxt. Если все они по умолчанию используют `3000`, это, конечно, не сработает. Поэтому я придумал простое и последовательное правило именования портов — «назначать» порты каждому проекту.\n[Исходный пост в блоге](https://lionad.art/articles/simple-naming-method)\n### Основная идея\nВместо выбора случайных чисел сопоставьте **название проекта с цифрами на основе клавиатуры**, чтобы порт был *читаемым* и *запоминающимся*.\nПока результат находится в допустимом диапазоне портов (**0–65535**) и не попадает в зарезервированные/системные порты, его можно использовать.\nБолее конкретно: используя стандартную клавиатуру QWERTY, сопоставьте каждой букве одну цифру в зависимости от её **позиции по строке/столбцу**.\nПример:\n`\"cfetch\"` → `c(3) f(4) e(3) t(5) c(3) h(6)` → `34353`（номер порта）\nЗатем вы можете взять первые 4 цифры (например, `3453`), или оставить больше цифр (например, `34353`). Оба варианта допустимы.\nЕсли проект требует несколько портов (frontend, backend, база данных и т.д.), выберите **один** из следующих подходов:\n1. Использовать префикс проекта, а затем добавить «суффикс роли»  \n   - Для `\"cfetch\"` берём `3435` как основу  \n   - Frontend (`fe`, т.е. `43`) → `34354`  \n   - Backend (`server`) → `34352`  \n   - Database (`mongo`) → `34357`  \n   - …и так далее\n2. Использовать префикс проекта, а затем назначать последовательные роли  \n   - Для `\"cfetch\"` берём `3435` как основу  \n   - Web → `34351`  \n   - Backend → `34352`  \n   - Database → `34353`  \n   - …и так далее\n### Диапазон допустимых портов\n- Порты должны находиться в пределах **0–65535**.\n- Для пользовательских сервисов обычно лучше использовать диапазон **1024–49151** (не зарезервированные) или **49152–65535** (частные/динамические).\n- Пока полученное число не превышает лимит, оно считается допустимым.\n---"
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@lionad/port-key-mcp",
+  "version": "0.1.6",
+  "description": "MCP Server for PortKey",
+  "bin": "./bin/port-key-mcp.js",
+  "type": "module",
+  "types": "./dist/mcp-cli.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/mcp-cli.d.ts",
+      "default": "./dist/mcp-cli.js"
+    }
+  },
+  "keywords": [
+    "portkey",
+    "port-key",
+    "port",
+    "port number",
+    "naming",
+    "strategy",
+    "method",
+    "mcp"
+  ],
+  "main": "dist/mcp-cli.js",
+  "files": [
+    "dist",
+    "bin",
+    "locales",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build:locales": "node scripts/build-locales.js",
+    "build": "pnpm run build:locales && tsc -p tsconfig.build.json",
+    "prepublishOnly": "pnpm run build",
+    "test": "pnpm run build && vitest run",
+    "test:watch": "vitest"
+  },
+  "author": "Lionad",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lionad-Morotar/port-key.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Lionad-Morotar/port-key/issues"
+  },
+  "homepage": "https://github.com/Lionad-Morotar/port-key#readme",
+  "engines": {
+    "node": ">=16"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@lionad/port-key": "^0.1.5",
+    "@modelcontextprotocol/sdk": "^1.24.1",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@cfworker/json-schema": "^4.1.1",
+    "@types/express": "^5.0.6",
+    "@types/node": "^24.7.2",
+    "vitest": "4.0.16"
+  }
+}