@manhq/localmcp 1.0.0

package/README.md

@@ -0,0 +1,239 @@
+# Local MCP Server
+
+[English](README.md) | [Tiếng Việt](README.vi.md)
+
+Self-hosted MCP server integrating Figma, Jira, and Google Chat for AI agents.
+
+## Requirements
+
+- Node.js 20+ (LTS)
+- npm 10+
+
+## Install & Run
+
+```bash
+# Install dependencies
+npm install
+
+# Create the configuration file
+cp .env.example .env
+```
+
+Fill credentials in `.env` (see each service doc below), then:
+
+```bash
+# Run in dev mode with auto reload
+npm run dev
+
+# Build & run production
+npm run build
+npm start
+```
+
+The server runs at `http://localhost:47001` by default.
+
+```bash
+# Open MCP Inspector while the server is running
+npm run inspect
+```
+
+## Flexible Run
+
+If you do not want to open the project every time, register a global command while developing locally:
+
+```bash
+npm run build
+npm link
+localmcp
+```
+
+After `npm link`, the `localmcp` command works from any directory.
+
+After publishing to npm, users can install it with:
+
+```bash
+npm install -g @manhq/localmcp
+localmcp init
+localmcp config
+localmcp
+```
+
+Default settings path:
+
+```bash
+~/localmcp/settings.json
+```
+
+Main commands:
+
+```bash
+localmcp                         # Run the MCP server
+localmcp init                    # Create settings for the first time
+localmcp list                    # List services and missing variables
+localmcp config                  # Open settings with vim or $EDITOR
+localmcp config figma            # Configure Figma with inline prompts
+localmcp config figma token=figd_xxx
+localmcp register                # Select AI agent, then localmcp or a service
+localmcp register codex --service figma
+localmcp inspect                 # Open MCP Inspector
+localmcp --version               # Show version
+```
+
+Environment variables still take precedence over the settings file, so quick overrides work:
+
+```bash
+PORT=47002 localmcp
+```
+
+Publish package:
+
+```bash
+npm publish --access=public
+```
+
+## Register with AI Agents
+
+**Claude Code** — `.claude/settings.local.json`
+```json
+{
+  "mcpServers": {
+    "localmcp": {
+      "url": "http://localhost:47001/mcp"
+    }
+  }
+}
+```
+
+Or register from the command line:
+```bash
+claude mcp add --transport http localmcp http://localhost:47001/mcp
+```
+
+**Codex** — `~/.codex/config.toml`
+```toml
+[mcp_servers.localmcp]
+url = "http://localhost:47001/mcp"
+```
+
+Or register from the command line:
+```bash
+codex mcp add localmcp --url http://localhost:47001/mcp
+```
+
+**GitHub Copilot / VS Code** — `.vscode/mcp.json`
+```json
+{
+  "servers": {
+    "localmcp": {
+      "type": "http",
+      "url": "http://localhost:47001/mcp"
+    }
+  }
+}
+```
+
+**Cursor** — `.cursor/mcp.json`
+```json
+{
+  "mcpServers": {
+    "localmcp": {
+      "url": "http://localhost:47001/mcp"
+    }
+  }
+}
+```
+
+**Windsurf** — `~/.codeium/windsurf/mcp_config.json`
+```json
+{
+  "mcpServers": {
+    "localmcp": {
+      "serverUrl": "http://localhost:47001/mcp"
+    }
+  }
+}
+```
+
+**Antigravity** — `~/.gemini/config/mcp_config.json`
+```json
+{
+  "mcpServers": {
+    "localmcp": {
+      "serverUrl": "http://localhost:47001/mcp"
+    }
+  }
+}
+```
+
+## Health Check
+
+```
+GET http://localhost:47001/health
+```
+
+Returns the active services and their corresponding endpoints.
+
+---
+
+## Services
+
+| Service | Dedicated endpoint | Docs |
+|---------|--------------------|------|
+| Figma | `/mcp/figma` | [EN](docs/figma.md) / [VI](docs/vi/figma.md) |
+| Atlassian | `/mcp/atlassian` | [EN](docs/atlassian.md) / [VI](docs/vi/atlassian.md) |
+| Google Chat | `/mcp/google-chat` | [EN](docs/google-chat.md) / [VI](docs/vi/google-chat.md) |
+
+The `/mcp` endpoint is combined: it exposes every active service through one server.
+
+Each service is enabled only when all required environment variables are present. See each service doc for required variables.
+
+---
+
+## Add a New Service
+
+### 1. Create the Folder Structure
+
+```
+src/services/<service-name>/
+  index.ts          # exports registerXxxTools(server)
+  client.ts         # axios client or SDK wrapper
+  types.ts          # TypeScript types
+  tools/
+    <feature>.ts    # registers tools with server.registerTool(...)
+```
+
+### 2. Register it in the Service Registry
+
+Open `src/index.ts`, then add it to `SERVICE_REGISTRY`:
+
+```ts
+import { registerXxxTools } from "./services/xxx/index.js";
+
+const SERVICE_REGISTRY = {
+  // ...existing services...
+  xxx: { register: registerXxxTools, enabled: !!env.xxx },
+};
+```
+
+### 3. Add Environment Variables
+
+Open `src/shared/env.ts`, then add a new optional group:
+
+```ts
+export const env = {
+  // ...
+  xxx: optionalGroup(["XXX_API_KEY"], () => ({
+    API_KEY: process.env["XXX_API_KEY"]!,
+  })),
+};
+```
+
+Add it to `.env.example`:
+
+```
+XXX_API_KEY=
+```
+
+### 4. Write Documentation
+
+Create `docs/<service-name>.md` and `docs/vi/<service-name>.md`, then add the service to the **Services** table in both README files.

package/README.vi.md

@@ -0,0 +1,239 @@
+# Local MCP Server
+
+[English](README.md) | [Tiếng Việt](README.vi.md)
+
+MCP server tự host, tích hợp Figma, Jira và Google Chat cho các AI agent.
+
+## Yêu cầu
+
+- Node.js 20+ (LTS)
+- npm 10+
+
+## Cài đặt & chạy
+
+```bash
+# Cài dependencies
+npm install
+
+# Tạo file cấu hình
+cp .env.example .env
+```
+
+Điền credentials vào `.env` (xem tài liệu từng service bên dưới), sau đó:
+
+```bash
+# Chạy ở chế độ dev (tự reload khi sửa code)
+npm run dev
+
+# Build & chạy production
+npm run build
+npm start
+```
+
+Server mặc định chạy tại `http://localhost:47001`.
+
+```bash
+# Mở MCP Inspector (chạy song song với server)
+npm run inspect
+```
+
+## Chạy linh hoạt
+
+Nếu không muốn mở project mỗi lần chạy, có thể đăng ký command global khi đang phát triển local:
+
+```bash
+npm run build
+npm link
+localmcp
+```
+
+Sau khi `npm link`, lệnh `localmcp` chạy được ở bất kỳ thư mục nào.
+
+Khi publish lên npm, người dùng có thể cài bằng:
+
+```bash
+npm install -g @manhq/localmcp
+localmcp init
+localmcp config
+localmcp
+```
+
+Settings mặc định nằm ở:
+
+```bash
+~/localmcp/settings.json
+```
+
+Các command chính:
+
+```bash
+localmcp                         # Chạy MCP server
+localmcp init                    # Tạo settings lần đầu
+localmcp list                    # Liệt kê services và biến còn thiếu
+localmcp config                  # Mở settings bằng vim hoặc $EDITOR
+localmcp config figma            # Config riêng service Figma bằng prompt inline
+localmcp config figma token=figd_xxx
+localmcp register                # Chọn AI agent, sau đó chọn localmcp hoặc service
+localmcp register codex --service figma
+localmcp inspect                 # Mở MCP Inspector
+localmcp --version               # Xem phiên bản
+```
+
+Biến môi trường vẫn được ưu tiên cao hơn settings file, nên có thể override nhanh:
+
+```bash
+PORT=47002 localmcp
+```
+
+Publish package:
+
+```bash
+npm publish --access=public
+```
+
+## Đăng ký với AI Agents
+
+**Claude Code** — `.claude/settings.local.json`
+```json
+{
+  "mcpServers": {
+    "localmcp": {
+      "url": "http://localhost:47001/mcp"
+    }
+  }
+}
+```
+
+Hoặc đăng ký bằng command line:
+```bash
+claude mcp add --transport http localmcp http://localhost:47001/mcp
+```
+
+**Codex** — `~/.codex/config.toml`
+```toml
+[mcp_servers.localmcp]
+url = "http://localhost:47001/mcp"
+```
+
+Hoặc đăng ký bằng command line:
+```bash
+codex mcp add localmcp --url http://localhost:47001/mcp
+```
+
+**GitHub Copilot / VS Code** — `.vscode/mcp.json`
+```json
+{
+  "servers": {
+    "localmcp": {
+      "type": "http",
+      "url": "http://localhost:47001/mcp"
+    }
+  }
+}
+```
+
+**Cursor** — `.cursor/mcp.json`
+```json
+{
+  "mcpServers": {
+    "localmcp": {
+      "url": "http://localhost:47001/mcp"
+    }
+  }
+}
+```
+
+**Windsurf** — `~/.codeium/windsurf/mcp_config.json`
+```json
+{
+  "mcpServers": {
+    "localmcp": {
+      "serverUrl": "http://localhost:47001/mcp"
+    }
+  }
+}
+```
+
+**Antigravity** — `~/.gemini/config/mcp_config.json`
+```json
+{
+  "mcpServers": {
+    "localmcp": {
+      "serverUrl": "http://localhost:47001/mcp"
+    }
+  }
+}
+```
+
+## Kiểm tra trạng thái
+
+```
+GET http://localhost:47001/health
+```
+
+Trả về danh sách services đang active và các endpoints tương ứng.
+
+---
+
+## Danh sách services
+
+| Service | Endpoint riêng | Tài liệu |
+|---------|---------------|----------|
+| Figma | `/mcp/figma` | [EN](docs/figma.md) / [VI](docs/vi/figma.md) |
+| Atlassian | `/mcp/atlassian` | [EN](docs/atlassian.md) / [VI](docs/vi/atlassian.md) |
+| Google Chat | `/mcp/google-chat` | [EN](docs/google-chat.md) / [VI](docs/vi/google-chat.md) |
+
+Endpoint `/mcp` là combined — gộp tất cả services đang active vào một server.
+
+Mỗi service chỉ được bật khi đủ biến môi trường. Xem tài liệu từng service để biết biến nào cần thiết.
+
+---
+
+## Thêm service mới
+
+### 1. Tạo cấu trúc thư mục
+
+```
+src/services/<tên-service>/
+  index.ts          # export registerXxxTools(server)
+  client.ts         # axios client hoặc SDK wrapper
+  types.ts          # TypeScript types
+  tools/
+    <feature>.ts    # đăng ký tool với server.registerTool(...)
+```
+
+### 2. Đăng ký vào service registry
+
+Mở `src/index.ts`, thêm vào `SERVICE_REGISTRY`:
+
+```ts
+import { registerXxxTools } from "./services/xxx/index.js";
+
+const SERVICE_REGISTRY = {
+  // ...services hiện có...
+  xxx: { register: registerXxxTools, enabled: !!env.xxx },
+};
+```
+
+### 3. Thêm biến môi trường
+
+Mở `src/shared/env.ts`, thêm optional group mới:
+
+```ts
+export const env = {
+  // ...
+  xxx: optionalGroup(["XXX_API_KEY"], () => ({
+    API_KEY: process.env["XXX_API_KEY"]!,
+  })),
+};
+```
+
+Thêm vào `.env.example`:
+
+```
+XXX_API_KEY=
+```
+
+### 4. Viết tài liệu
+
+Tạo `docs/<tên-service>.md` theo mẫu các service hiện có, sau đó thêm dòng vào bảng **Danh sách services** ở README này.

package/bin/localmcp.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const distEntry = resolve(packageRoot, "dist/cli.js");
+
+const run = (command, args, cwd = process.cwd()) => {
+  const child = spawn(command, args, {
+    cwd,
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+
+    process.exit(code ?? 0);
+  });
+};
+
+if (existsSync(distEntry)) {
+  run(process.execPath, [distEntry, ...process.argv.slice(2)]);
+} else {
+  run("npx", ["tsx", "src/cli.ts", ...process.argv.slice(2)], packageRoot);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export declare function runCli(argv?: string[]): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAuBA,wBAAsB,MAAM,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCxE"}