@andy-toolforge/mcp

MCP (Model Context Protocol) server cho hệ sinh thái @andy-toolforge. Expose 20+ tools qua MCP protocol để AI agents có thể sử dụng trực tiếp. Thuộc hệ sinh thái toolforge.

Tính năng

• Plugin discovery — tự động phát hiện tools từ tất cả @andy-toolforge/* packages đã cài
• 20+ tools — phân tích script, SEO, research, business analysis, book writing
• toolforge_suggest — LLM-powered router: gõ câu hỏi tự nhiên, server gợi ý đúng tool
• Không config — cài package là có tools ngay

Installation

npm install @andy-toolforge/mcp

Sẽ tự động cài kèm @andy-toolforge/core + @andy-toolforge/footage-generation + @andy-toolforge/content-research.

Usage

CLI (standalone)

export GEMINI_API_KEY="your-key"
npx toolforge-mcp

Server nhận diện provider từ env: GROQ_API_KEY > GEMINI_API_KEY. Có thể set GROQ_MODEL / GEMINI_MODEL.

Embed trong code

const { createServer } = require('@andy-toolforge/mcp');

const server = createServer({
    provider: 'gemini',
    apiKey: process.env.GEMINI_API_KEY,
    // discover: false  // Tắt plugin discovery nếu muốn
});
server.start(); // stdio transport

Cấu hình trong OpenCode / Claude Desktop / Cursor

{
  "mcpServers": {
    "toolforge": {
      "command": "npx",
      "args": ["toolforge-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key"
      }
    }
  }
}

Cấu hình API Key

Server cần ít nhất một API key để hoạt động (hầu hết tools đều dùng LLM). Provider được chọn theo thứ tự ưu tiên: GROQ_API_KEY > GEMINI_API_KEY.

Cách 1: Biến môi trường (dùng cho terminal)

export GEMINI_API_KEY="AIza_xxx"
export GROQ_API_KEY="gsk_xxx"
npx toolforge-mcp

Cách 2: Config trong OpenCode/Claude Desktop / Cursor (dùng cho GUI app)

macOS GUI apps (OpenCode GUI, Claude Desktop, Cursor) không load .zshrc hay .bash_profile. API key phải được khai báo trực tiếp trong config.

Cách đơn giản nhất — truyền key thẳng vào env:

{
  "mcpServers": {
    "toolforge": {
      "command": "npx",
      "args": ["toolforge-mcp"],
      "env": {
        "GEMINI_API_KEY": "AIza_your_key_here",
        "GROQ_API_KEY": "gsk_your_key_here"
      }
    }
  }
}

Hoặc dùng ${VAR} syntax — client app sẽ resolve từ environment của nó:

{
  "mcpServers": {
    "toolforge": {
      "command": "npx",
      "args": ["toolforge-mcp"],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}",
        "GROQ_API_KEY": "${GROQ_API_KEY}"
      }
    }
  }
}

Hướng dẫn theo từng app

| App | Cách set env để dùng ${VAR} syntax | |-----|--------------------------------------| | OpenCode GUI | (Xem hướng dẫn chi tiết bên dưới) | | Claude Desktop | Dùng launchctl setenv GEMINI_API_KEY "AIza_xxx" trong terminal, restart app | | Cursor | Thêm vào ~/.zshrc rồi launch Cursor từ terminal (open -a Cursor) | | VS Code | Dùng extension "Remote - SSH" hoặc set trong .vscode/launch.json → env field |

Hướng dẫn chi tiết cho OpenCode GUI

OpenCode GUI là macOS native app — không load .zshrc hay .bash_profile. Có 3 cách để cấp API key:

Cách A — Config trong opencode.jsonc (nhanh nhất)

Sửa file ~/.config/opencode/opencode.jsonc, thêm environment field:

{
  "mcpServers": {
    "toolforge": {
      "command": "npx",
      "args": ["toolforge-mcp"],
      "env": {
        "GEMINI_API_KEY": "AIza_your_key_here",
        "GROQ_API_KEY": "gsk_your_key_here"
      }
    }
  }
}

Hoặc nếu bạn đã set biến trong global environment của OpenCode, dùng ${VAR} syntax:

{
  "environment": {
    "GEMINI_API_KEY": "AIza_xxx",
    "GROQ_API_KEY": "gsk_xxx"
  },
  "mcpServers": {
    "toolforge": {
      "command": "npx",
      "args": ["toolforge-mcp"],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}",
        "GROQ_API_KEY": "${GROQ_API_KEY}"
      }
    }
  }
}

Cách B — .env file (an toàn hơn, không lộ secret trong config)

Tạo file .env ở thư mục project (nơi bạn mở OpenCode):

GEMINI_API_KEY=AIza_xxx
GROQ_API_KEY=gsk_xxx

OpenCode GUI tự động đọc .env và resolve ${VAR} trong MCP config. File này có thể add vào .gitignore.

Cách C — launchctl setenv (dùng chung cho mọi GUI app)

launchctl setenv GEMINI_API_KEY "AIza_xxx"
launchctl setenv GROQ_API_KEY "gsk_xxx"
# Restart OpenCode GUI

Biến có hiệu lực đến lần reboot. Để tự động, tạo LaunchAgent plist hoặc thêm vào script startup.

Cách 3: .env file (nếu client app hỗ trợ)

Một số GUI apps (như OpenCode) tự động đọc .env trong project directory. Tạo file .env:

GEMINI_API_KEY=AIza_xxx
GROQ_API_KEY=gsk_xxx

Cách 4: launchctl setenv (cho macOS GUI apps)

launchctl setenv GEMINI_API_KEY "AIza_xxx"
launchctl setenv GROQ_API_KEY "gsk_xxx"
# Sau đó restart GUI app

Biến sẽ có hiệu lực cho đến lần reboot. Để tự động hoá, tạo LaunchAgent plist.

Lưu ý

• toolforge_suggest là tool duy nhất cần LLM — các tool còn lại (footage-generation, book-writing, v.v.) vẫn chạy không cần API key, chỉ báo lỗi khi thực sự gọi LLM.
• Server không crash nếu thiếu API key — chỉ warning và cho các tool khác hoạt động bình thường.

Plugin Discovery — Cách hoạt động

Khi MCP server khởi động:

1. Quét node_modules/@andy-toolforge/*/mcp-tools.js
2. Load mỗi file, gọi hàm export với config
3. Nếu tool name trùng với built-in → built-in được ưu tiên (ghi log warning)
4. Lỗi ở một package không ảnh hưởng đến các package khác
5. Cuối cùng, thêm toolforge_suggest — LLM router

// Cấu trúc một mcp-tools.js điển hình:
module.exports = function(config) {
    return [
        {
            definition: { name: 'my_tool', description: '...', inputSchema: { ... } },
            handler: async (llm, args) => { /* ... */ }
        }
    ];
};

toolforge_suggest

Built-in LLM router tool. Mô tả task bằng ngôn ngữ tự nhiên, server trả về tool phù hợp:

// Input: { "task": "Tôi muốn phân tích script podcast mới" }
// Output:
{
  "bestTool": "analyze_script",
  "reason": "Phân tích script podcast → visual segments",
  "suggestedArgs": { "script": "...", "title": "..." }
}

Full Tool List (20+ tools)

Từ footage-generation (4 tools)

| Tool | Description | |------|-------------| | analyze_script | Analyze podcast script → visual segments + prompts | | generate_prompts | Generate 5 image prompts per segment (5 visual styles) | | generate_mapping | Map background music + sound design per segment | | suggest_cover | Suggest cover art (series/episode/thumbnail) |

Từ seo-generation (1 tool)

| Tool | Description | |------|-------------| | toolforge_seo_generate | Generate SEO metadata for YouTube, TikTok, Facebook |

Từ content-research (4 tools)

| Tool | Description | |------|-------------| | andy_toolforge_content_summarizer | Summarize articles/reports via LLM | | andy_toolforge_content_ideator | Generate content ideas | | andy_toolforge_article_manager | Classify, tag, summarize, improve articles | | andy_toolforge_competitor_analyzer | Crawl competitor URL + LLM analysis |

Từ content-operations (1 tool)

| Tool | Description | |------|-------------| | toolforge_content_research | Research trends, keywords, competitors, gaps, ideas |

Từ ba-support (5 tools)

| Tool | Description | |------|-------------| | toolforge_competitor_analysis | Crawl competitor data + profile | | toolforge_pricing_analysis | Analyze pricing data, strategic insights | | toolforge_swot_analysis | Generate SWOT from competitor data | | toolforge_trend_analysis | Analyze market trends for keywords | | toolforge_business_report | Generate comprehensive business report |

Từ book-writing (4 tools)

| Tool | Description | |------|-------------| | toolforge_book_outline | Generate book outline from topic | | toolforge_book_write_chapter | Write a chapter with continuity | | toolforge_book_review | Review manuscript for consistency | | toolforge_book_export | Export to markdown/plain/html |

Built-in (1 tool)

| Tool | Description | |------|-------------| | toolforge_suggest | LLM-powered router: mô tả task → gợi ý tool phù hợp |

Cài thêm tools

# Install thêm package → tools tự động xuất hiện
npm install @andy-toolforge/ba-support   # +5 tools (competitor, pricing, SWOT, trends, report)
npm install @andy-toolforge/book-writing # +4 tools (outline, write, review, export)
# Không cần config lại MCP server — plugin discovery tự động

API Reference (Embed)

const { createServer, MCPServer } = require('@andy-toolforge/mcp');

// createServer(config) — shorthand
const server = createServer({
    apiKey: '...',      // required
    provider: 'gemini',  // 'gemini' | 'groq'
    model: '...',        // override default model
    discover: true,      // false để tắt plugin discovery
});
server.start();

// MCPServer class — full control
const server2 = new MCPServer({ ... });
await server2.start();

Related

• @andy-toolforge/core — LLMClient used internally
• Đọc spec đầy đủ — Architecture decisions & future plans
• Model Context Protocol — spec