@aibuilders/mcp-coach-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AI Builders
+
+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,123 @@
+# AI Builders MCP Coach Server
+
+MCP服务器作为AI部署教练，通过标准化接口向AI传授部署知识、API调用方法和最佳实践。
+
+## 核心功能
+
+- **get_api_specification()**: 获取AI Builders平台的OpenAPI规范和endpoint信息
+- **get_deployment_guide()**: 获取部署指导（带缓存机制）
+- **explain_authentication_model()**: 详细解释认证机制和使用最佳实践
+- **get_auth_token()**: 返回环境中的 AI_BUILDER_TOKEN（默认打码）
+- **create_env_file()**: 在指定目录创建包含 AI_BUILDER_TOKEN 的 .env 文件
+
+## 本地开发和使用
+
+### 快速开始（开发模式）
+
+```bash
+# 1. 克隆项目
+git clone <repository-url>
+cd student_portal_mcp
+
+# 2. 安装依赖
+npm install
+
+# 3. 配置环境变量
+cp .env.example .env
+# 编辑 .env 文件，添加你的 AI_BUILDER_TOKEN
+
+# 4. 运行开发服务器
+npm run dev
+```
+
+### 使用MCP Inspector测试
+
+```bash
+# 安装Inspector
+npm install -g @modelcontextprotocol/inspector
+
+# 运行Inspector（在另一个终端）
+mcp-inspector
+
+# 在Inspector界面中，选择以下任一方式：
+# 方式1（推荐）: npx tsx /Users/grapeot/co/student_portal_mcp/src/index.ts
+# 方式2: node /Users/grapeot/co/student_portal_mcp/dist/index.js
+# 然后点击 Connect
+```
+
+### 正式发布后使用
+
+等发布到npm后，可以这样使用：
+
+```bash
+# 安装
+npm install -g @ai-builders/mcp-coach-server
+
+# 运行
+npx @ai-builders/mcp-coach-server
+```
+
+### 配置到AI编辑器
+
+在Claude Desktop配置文件中添加：
+
+```json
+{
+  "mcpServers": {
+    "ai-builders-coach": {
+      "command": "npx",
+      "args": ["tsx", "/Users/grapeot/co/student_portal_mcp/src/index.ts"],
+      "env": {
+        "AI_BUILDER_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+## 工具使用示例
+
+```json
+{
+  "tool": "get_api_specification",
+  "arguments": {}
+}
+```
+
+返回内容为英文，并包含：
+- `endpoint_info.base_url`（自动从 OpenAPI servers 推断）
+- `sdk_compatibility.openai_sdk_compatible`（标注兼容 OpenAI SDK）
+- 示例：`/v1/chat/completions`
+
+```json
+{
+  "tool": "get_auth_token",
+  "arguments": { "masked": true }
+}
+```
+
+返回打码后的 token；若需要写入 .env：
+
+```json
+{
+  "tool": "create_env_file",
+  "arguments": { "target_dir": "/path/to/project", "overwrite": false }
+}
+```
+
+## 开发
+
+```bash
+# 克隆项目
+git clone <repository-url>
+cd ai-builders-mcp-coach
+
+# 安装依赖
+npm install
+
+# 开发模式运行
+npm run dev
+
+# 构建
+npm run build
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,314 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import dotenv from "dotenv";
+import { readFile, writeFile, access, mkdir } from "fs/promises";
+import { join } from "path";
+import { homedir } from "os";
+dotenv.config();
+const CACHE_DIR = join(homedir(), ".ai-builders-mcp-cache");
+const DEPLOYMENT_GUIDE_CACHE = join(CACHE_DIR, "deployment_guide_cache.json");
+async function ensureCacheDir() {
+    try {
+        await access(CACHE_DIR);
+    }
+    catch {
+        await mkdir(CACHE_DIR, { recursive: true });
+    }
+}
+function getDefaultDeploymentGuide(serviceType = "fastapi") {
+    return `# ${serviceType.toUpperCase()} Service Deployment Guide
+
+## Prerequisites
+- Public GitHub repository
+- Listen on PORT environment variable
+- Include dependency files (requirements.txt/package.json)
+
+## Deployment Steps
+1. Prepare a Dockerfile
+2. Configure environment variables
+3. Set AI_BUILDER_TOKEN
+4. Deploy to target platform
+
+## Authentication
+- Use Bearer Token authentication
+- Read AI_BUILDER_TOKEN from environment variables
+- Include token in Authorization header
+
+## Environment Example
+\`\`\`bash
+AI_BUILDER_TOKEN=your_token_here
+DEPLOYMENT_TARGET=production
+PORT=8000
+\`\`\`
+
+## Code Example
+\`\`\`python
+import os
+
+token = os.getenv("AI_BUILDER_TOKEN")
+headers = {"Authorization": f"Bearer {token}"}
+\`\`\``;
+}
+async function getCachedDeploymentGuide() {
+    await ensureCacheDir();
+    try {
+        const cacheContent = await readFile(DEPLOYMENT_GUIDE_CACHE, 'utf-8');
+        const cacheData = JSON.parse(cacheContent);
+        const cachedTime = new Date(cacheData.cached_at);
+        const now = new Date();
+        if (now.getTime() - cachedTime.getTime() < 24 * 60 * 60 * 1000) {
+            return cacheData;
+        }
+    }
+    catch {
+    }
+    try {
+        const response = await fetch("https://www.ai-builders.com/resources/students/deployment-prompt.md");
+        if (response.ok) {
+            const content = await response.text();
+            const cacheData = {
+                content,
+                cached_at: new Date().toISOString(),
+                source: "remote"
+            };
+            try {
+                await writeFile(DEPLOYMENT_GUIDE_CACHE, JSON.stringify(cacheData, null, 2));
+            }
+            catch (error) {
+                console.error("Cache write failed:", error);
+            }
+            return cacheData;
+        }
+    }
+    catch (error) {
+        console.error("Failed to fetch remote deployment guide:", error);
+    }
+    return {
+        content: getDefaultDeploymentGuide(),
+        cached_at: new Date().toISOString(),
+        source: "default"
+    };
+}
+const server = new Server({
+    name: "ai-builders-coach",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "get_api_specification": {
+                const response = await fetch("https://www.ai-builders.com/resources/students-backend/openapi.json");
+                if (!response.ok) {
+                    throw new Error(`Failed to fetch OpenAPI specification: HTTP ${response.status}`);
+                }
+                const openapiSpec = await response.json();
+                let baseUrl = "https://www.ai-builders.com/resources/students-backend";
+                try {
+                    if (openapiSpec?.servers?.length) {
+                        const url = openapiSpec.servers[0].url;
+                        if (url.startsWith("http")) {
+                            baseUrl = url;
+                        }
+                        else {
+                            baseUrl = `https://www.ai-builders.com${url}`;
+                        }
+                    }
+                }
+                catch { }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                openapi_spec: openapiSpec,
+                                endpoint_info: {
+                                    base_url: baseUrl,
+                                    description: "Base URL for the AI Builders API",
+                                    note: "All API calls should use this base URL"
+                                },
+                                authentication: {
+                                    type: "bearer_token",
+                                    header: "Authorization: Bearer {AI_BUILDER_TOKEN}",
+                                    token_source: "Environment variable AI_BUILDER_TOKEN"
+                                },
+                                sdk_compatibility: {
+                                    openai_sdk_compatible: true,
+                                    recommendation: "We strongly recommend using the OpenAI SDK to interact with this API. It provides a clean, well-documented interface and handles authentication automatically.",
+                                    usage_note: "You can use OpenAI-compatible SDKs against this API. The OpenAI SDK is the recommended approach.",
+                                    example_node: {
+                                        baseURL: baseUrl,
+                                        endpoint: "/v1/chat/completions",
+                                        code_example: `import OpenAI from 'openai';\n\nconst openai = new OpenAI({\n  baseURL: '${baseUrl}',\n  apiKey: process.env.AI_BUILDER_TOKEN,\n});\n\nconst completion = await openai.chat.completions.create({\n  model: 'gpt-4',\n  messages: [{ role: 'user', content: 'Hello!' }],\n});`
+                                    },
+                                    example_python: {
+                                        code_example: `from openai import OpenAI\nimport os\n\nclient = OpenAI(\n    base_url='${baseUrl}',\n    api_key=os.getenv('AI_BUILDER_TOKEN')\n)\n\ncompletion = client.chat.completions.create(\n    model='gpt-4',\n    messages=[{'role': 'user', 'content': 'Hello!'}]\n)`
+                                    }
+                                },
+                                mcp_recommendation: {
+                                    note: "If running via an MCP server, call get_auth_token to retrieve AI_BUILDER_TOKEN and configure your environment manually",
+                                    tools: ["get_auth_token"],
+                                    env_key: "AI_BUILDER_TOKEN"
+                                }
+                            }, null, 2)
+                        }
+                    ]
+                };
+            }
+            case "get_deployment_guide": {
+                const serviceType = args?.service_type || "fastapi";
+                const cachedGuide = await getCachedDeploymentGuide();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                deployment_guide: cachedGuide.content,
+                                service_type: serviceType,
+                                cached_at: cachedGuide.cached_at,
+                                source: cachedGuide.source,
+                                authentication_note: "Both deployment and development require AI_BUILDER_TOKEN; manage it via a .env file"
+                            }, null, 2)
+                        }
+                    ]
+                };
+            }
+            case "explain_authentication_model": {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                authentication_model: {
+                                    token_type: "AI_BUILDER_TOKEN",
+                                    usage_scenarios: ["deployment", "development", "api_calls"],
+                                    shared_principle: "Use the same token for both deployment and development",
+                                    best_practices: [
+                                        ".env file management",
+                                        "Do not hardcode tokens",
+                                        "Add .env to .gitignore",
+                                        "Use different tokens per environment"
+                                    ]
+                                },
+                                environment_setup: {
+                                    example_env_content: "AI_BUILDER_TOKEN=your_token_here\nDEPLOYMENT_TARGET=development",
+                                    loading_method: "Load environment variables using dotenv or similar",
+                                    usage_example: `import os\nfrom dotenv import load_dotenv\n\nload_dotenv()\n\ntoken = os.getenv("AI_BUILDER_TOKEN")\nheaders = {"Authorization": f"Bearer {token}"}`
+                                },
+                                deployment_note: "Platforms may inject AI_BUILDER_TOKEN at deploy time; set it manually during development"
+                            }, null, 2)
+                        }
+                    ]
+                };
+            }
+            case "get_auth_token": {
+                const masked = args?.masked !== false;
+                const token = process.env.AI_BUILDER_TOKEN || "";
+                const available = !!token;
+                let value = token;
+                if (masked && token) {
+                    const start = token.slice(0, 4);
+                    const end = token.slice(-4);
+                    value = `${start}${"*".repeat(Math.max(0, token.length - 8))}${end}`;
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                available,
+                                token: value,
+                                masked,
+                                note: available
+                                    ? "Use this token to configure your .env as AI_BUILDER_TOKEN"
+                                    : "AI_BUILDER_TOKEN is not set in server environment"
+                            }, null, 2)
+                        }
+                    ]
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: errorMessage,
+                        suggestion: "Check network connection or retry later"
+                    })
+                }
+            ],
+            isError: true
+        };
+    }
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "get_api_specification",
+                description: "Retrieve the OpenAPI specification with endpoint details",
+                inputSchema: {
+                    type: "object",
+                    properties: {}
+                }
+            },
+            {
+                name: "get_deployment_guide",
+                description: "Get deployment guidance with caching",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        service_type: {
+                            type: "string",
+                            description: "Service type (e.g., fastapi, express)",
+                            default: "fastapi"
+                        }
+                    }
+                }
+            },
+            {
+                name: "explain_authentication_model",
+                description: "Explain authentication model for shared deployment and development use",
+                inputSchema: {
+                    type: "object",
+                    properties: {}
+                }
+            },
+            {
+                name: "get_auth_token",
+                description: "Return AI_BUILDER_TOKEN from environment (masked by default)",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        masked: {
+                            type: "boolean",
+                            description: "Return masked token if true",
+                            default: true
+                        }
+                    }
+                }
+            }
+        ]
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("AI Builders MCP Coach Server started");
+}
+main().catch((error) => {
+    console.error("Server failed to start:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@aibuilders/mcp-coach-server",
+  "version": "1.0.0",
+  "description": "MCP server as AI deployment coach for AI Builders platform",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "mcp-coach-server": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "tsx src/test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "deployment",
+    "coach",
+    "ai-builders"
+  ],
+  "author": "AI Builders",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "dotenv": "^16.4.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "README.md",
+    "LICENSE"
+  ]
+}