@liangshanli/mcp-server-project-standards 3.0.2 → 5.1.0

package/README.md

@@ -4,6 +4,17 @@ A MCP (Model Context Protocol) server for project standards management, designed
 
 ## 📋 Version Updates
 
+### v5.1.0 (2025-12-22)
+- **New Tool**: Added `download_file` tool to download files from URL to project path.
+- **Version Sync**: Updated server and package versions to 5.1.0.
+
+### v5.0.0 (2025-12-19) - Major Release
+- **Project Path Support**: Added `PROJECT_PATH` environment variable for resolving relative paths.
+- **Cursor Detection**: Automatic identification of Cursor IDE for enhanced features.
+- **New Tools**: Added `list_directory`, `generate_cursorrules`, and `generate_rules`.
+- **AI Guidance**: Integrated AI Enforcement Rules into rule generation templates.
+- **Security**: Added path validation for directory listing.
+
 ### v3.0.0 (2025-10-31) - Major Release
 
 #### 🚀 Breaking Changes
@@ -78,6 +89,10 @@ A MCP (Model Context Protocol) server for project standards management, designed
 
 ## 🚀 Core Advantages
 
+### 💰 Token Cost Optimization
+- **Efficient Context Caching**: By using MCP tools to retrieve short, structured standard data instead of reading long documents, it triggers model Context Caching more effectively (e.g., Gemini 3 Flash), significantly reducing input costs (down to $0.05/1M).
+- **Incremental Output**: Enforces minimal code diffs and precise tool responses, minimizing high-cost output token consumption.
+
 ### 🎯 Solving Multi-Machine Development Chaos
 - **Unified Standards**: AI assistants on multiple machines use the same project standards, avoiding inconsistent development styles
 - **Team Collaboration**: Eliminates code style differences caused by different developers using different AI configurations
@@ -104,6 +119,7 @@ A MCP (Model Context Protocol) server for project standards management, designed
 - ✅ **Configuration Management** - JSON-based configuration storage and management
 - ✅ **Auto-Restart** - Intelligent process management and fault recovery
 - ✅ **Health Checks** - Real-time service status and performance monitoring
+- ✅ **File Downloader** - Download files from URLs directly to the project directory
 
 ## 🎯 Application Scenarios
 
@@ -149,7 +165,8 @@ The server uses the `./.setting/` directory to store configuration files by defa
 
 | Variable | Default | Description | Example |
 |----------|---------|-------------|---------|
-| CONFIG_DIR | ./.setting or ./.setting.<TOOL_PREFIX> | Configuration directory. If set, used as-is; else if TOOL_PREFIX set, uses ./.setting.<TOOL_PREFIX>; else ./.setting | `export CONFIG_DIR="./config"` |
+| PROJECT_PATH | . | Root path of the project. Supports both absolute (e.g., `/` or `C:\`) and relative paths. Used to resolve all relative paths. | `export PROJECT_PATH="/path/to/project"` |
+| CONFIG_DIR | ./.setting or ./.setting.<TOOL_PREFIX> | Configuration directory. Resolved relative to PROJECT_PATH. | `export CONFIG_DIR="./config"` |
 | TOOL_PREFIX |  | Optional tool prefix for tool names and config isolation | `export TOOL_PREFIX="projA"` |
 | PROJECT_NAME |  | Optional project branding for tool descriptions | `export PROJECT_NAME="MyProject"` |
 | API_DEBUG_ALLOWED_METHODS | GET | Control allowed request methods (supports: GET,POST,PUT,DELETE,PATCH, etc.) | `export API_DEBUG_ALLOWED_METHODS="GET,POST"` |
@@ -247,6 +264,7 @@ npm run dev
       "command": "npx",
       "args": ["@liangshanli/mcp-server-project-standards"],
       "env": {
+        "PROJECT_PATH": ".",
         "CONFIG_DIR": "./.setting",
         "API_DEBUG_ALLOWED_METHODS": "GET,POST,PUT,DELETE",
         "API_DEBUG_LOGIN_URL": "/api/login",
@@ -268,6 +286,7 @@ npm run dev
       "command": "npx",
       "args": ["@liangshanli/mcp-server-project-standards"],
       "env": {
+        "PROJECT_PATH": ".",
         "TOOL_PREFIX": "projA",
         "PROJECT_NAME": "Project A",
         "API_DEBUG_ALLOWED_METHODS": "GET,POST,PUT,DELETE",
@@ -280,6 +299,7 @@ npm run dev
       "command": "npx",
       "args": ["@liangshanli/mcp-server-project-standards"],
       "env": {
+        "PROJECT_PATH": ".",
         "TOOL_PREFIX": "projB",
         "PROJECT_NAME": "Project B",
         "API_DEBUG_ALLOWED_METHODS": "GET,POST,PUT,DELETE",
@@ -303,6 +323,7 @@ npm run dev
       "command": "npx",
       "args": ["@liangshanli/mcp-server-project-standards"],
       "env": {
+        "PROJECT_PATH": ".",
         "CONFIG_DIR": "./.setting",
         "API_DEBUG_ALLOWED_METHODS": "GET,POST,PUT,DELETE",
         "API_DEBUG_LOGIN_URL": "/api/login",
@@ -323,6 +344,7 @@ npm run dev
       "command": "npx",
       "args": ["@liangshanli/mcp-server-project-standards"],
       "env": {
+        "PROJECT_PATH": ".",
         "TOOL_PREFIX": "projA",
         "PROJECT_NAME": "Project A",
         "API_DEBUG_ALLOWED_METHODS": "GET,POST,PUT,DELETE",
@@ -335,6 +357,7 @@ npm run dev
       "command": "npx",
       "args": ["@liangshanli/mcp-server-project-standards"],
       "env": {
+        "PROJECT_PATH": ".",
         "TOOL_PREFIX": "projB",
         "PROJECT_NAME": "Project B",
         "API_DEBUG_ALLOWED_METHODS": "GET,POST,PUT,DELETE",
@@ -544,6 +567,72 @@ The API debugging tool supports a complete login authentication flow, making it
 
 This design eliminates the need for manual authentication state management, as the tool automatically handles login and token updates, greatly simplifying the API debugging process!
 
+### 7. Directory Listing (list_directory)
+Recursively explores the directory structure relative to the project root.
+
+**Parameters:**
+- `path` (optional): Subdirectory path to list.
+- `depth` (optional): Max recursion depth (default: 2).
+
+**Example:**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 10,
+  "method": "tools/call",
+  "params": {
+    "name": "list_directory",
+    "arguments": {
+      "depth": 3
+    }
+  }
+}
+```
+
+### 8. Rule Generation (generate_cursorrules / generate_rules)
+Generates AI project guidance files (`.cursorrules` for Cursor, `PROJECT_RULES.md` for others) based on your standards.
+
+**Parameters:**
+- `save` (optional): Whether to save content to disk (default: false).
+
+**Example:**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 11,
+  "method": "tools/call",
+  "params": {
+    "name": "generate_cursorrules",
+    "arguments": {
+      "save": true
+    }
+  }
+}
+```
+
+### 9. File Download Tool (download_file)
+Download a file from a URL and save it to a specified path within the project.
+
+**Parameters:**
+- `url` (required): The URL of the file to download.
+- `savePath` (required): The path where the file should be saved (relative to project path or absolute).
+
+**Example:**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 12,
+  "method": "tools/call",
+  "params": {
+    "name": "download_file",
+    "arguments": {
+      "url": "https://example.com/logo.png",
+      "savePath": "assets/logo.png"
+    }
+  }
+}
+```
+
 ## 🔗 Related Tools for Collaborative Use
 
 To provide a more complete development experience, we recommend using the following MCP tools in collaboration:

package/README.zh-CN.md

@@ -4,6 +4,17 @@
 
 ## 📋 版本更新说明
 
+### v5.1.0 (2025-12-22)
+- **新增工具**：新增 `download_file` 工具，支持从 URL 下载文件到项目目录。
+- **版本同步**：服务器和包版本更新至 5.1.0。
+
+### v5.0.0 (2025-12-19) - 重大更新
+- **项目路径支持**：新增 `PROJECT_PATH` 环境变量，支持相对于项目根目录解析路径。
+- **Cursor 自动识别**：初始化时自动识别 Cursor 编辑器，开启环境特有的增强模式。
+- **新增工具**：新增 `list_directory`、`generate_cursorrules` 及 `generate_rules` 工具。
+- **AI 行为准则**：在规则生成模板中集成了完善的 AI 行为准则与强制执行逻辑。
+- **安全性增强**：为目录扫描工具增加了路径越界校验。
+
 ### v3.0.0 (2025-10-31) - 重大更新
 
 #### 🚀 破坏性变更
@@ -62,6 +73,10 @@
 
 ## 🚀 核心优势
 
+### 💰 Token 成本优化
+- **高效 Context Caching**：通过 MCP 工具获取短小、结构化的标准数据而非读取冗长文档，能更有效地触发模型的 Context Caching（上下文缓存，如 Gemini 3 Flash），将输入成本降低至极低水平（约 $0.05/1M）。
+- **增量式输出**：强制执行最小化代码 Diff 和精简的工具响应，最大限度减少高昂的输出 Token 消耗。
+
 ### 🎯 解决多机器开发混乱问题
 - **统一标准**：多台机器上的 AI 助手使用相同的项目标准，避免开发风格不一致
 - **团队协作**：消除因不同开发者使用不同 AI 配置导致的代码风格差异
@@ -88,6 +103,7 @@
 - ✅ **配置管理** - 基于 JSON 文件的配置存储和管理
 - ✅ **自动重启** - 智能的进程管理和故障恢复
 - ✅ **健康检查** - 实时监控服务状态和性能
+- ✅ **文件下载** - 支持从 URL 直接下载文件到项目目录
 
 ## 🎯 应用场景
 
@@ -133,7 +149,8 @@ npm install
 
 | 变量名 | 默认值 | 描述 | 示例 |
 |--------|--------|------|------|
-| CONFIG_DIR | ./.setting 或 ./.setting.<TOOL_PREFIX> | 配置目录。若设置则直接使用；否则若设置了 TOOL_PREFIX 则使用 ./.setting.<TOOL_PREFIX>；否则 ./.setting | `export CONFIG_DIR="./config"` |
+| PROJECT_PATH | . | 项目根路径。支持绝对路径（如 `/` 或 `C:\`）和相对路径。用于解析所有相对路径。 | `export PROJECT_PATH="/path/to/project"` |
+| CONFIG_DIR | ./.setting 或 ./.setting.<TOOL_PREFIX> | 配置目录。相对于 PROJECT_PATH 解析。 | `export CONFIG_DIR="./config"` |
 | TOOL_PREFIX |  | 工具名前缀，同时用于多项目配置隔离 | `export TOOL_PREFIX="projA"` |
 | PROJECT_NAME |  | 工具描述前添加项目名称用于标识 | `export PROJECT_NAME="MyProject"` |
 | API_DEBUG_ALLOWED_METHODS | GET | 控制允许的请求方法（支持：GET,POST,PUT,DELETE,PATCH等） | `export API_DEBUG_ALLOWED_METHODS="GET,POST"` |
@@ -231,6 +248,7 @@ npm run dev
       "command": "npx",
       "args": ["@liangshanli/mcp-server-project-standards"],
       "env": {
+        "PROJECT_PATH": ".",
         "CONFIG_DIR": "./.setting",
         "API_DEBUG_ALLOWED_METHODS": "GET,POST,PUT,DELETE",
         "API_DEBUG_LOGIN_URL": "/api/login",
@@ -252,6 +270,7 @@ npm run dev
       "command": "npx",
       "args": ["@liangshanli/mcp-server-project-standards"],
       "env": {
+        "PROJECT_PATH": ".",
         "TOOL_PREFIX": "projA",
         "PROJECT_NAME": "项目A",
         "API_DEBUG_ALLOWED_METHODS": "GET,POST,PUT,DELETE",
@@ -264,6 +283,7 @@ npm run dev
       "command": "npx",
       "args": ["@liangshanli/mcp-server-project-standards"],
       "env": {
+        "PROJECT_PATH": ".",
         "TOOL_PREFIX": "projB",
         "PROJECT_NAME": "项目B",
         "API_DEBUG_ALLOWED_METHODS": "GET,POST,PUT,DELETE",
@@ -287,6 +307,7 @@ npm run dev
       "command": "npx",
       "args": ["@liangshanli/mcp-server-project-standards"],
       "env": {
+        "PROJECT_PATH": ".",
         "CONFIG_DIR": "./.setting",
         "API_DEBUG_ALLOWED_METHODS": "GET,POST,PUT,DELETE",
         "API_DEBUG_LOGIN_URL": "/api/login",
@@ -307,6 +328,7 @@ npm run dev
       "command": "npx",
       "args": ["@liangshanli/mcp-server-project-standards"],
       "env": {
+        "PROJECT_PATH": ".",
         "TOOL_PREFIX": "projA",
         "PROJECT_NAME": "项目A",
         "API_DEBUG_ALLOWED_METHODS": "GET,POST,PUT,DELETE",
@@ -319,6 +341,7 @@ npm run dev
       "command": "npx",
       "args": ["@liangshanli/mcp-server-project-standards"],
       "env": {
+        "PROJECT_PATH": ".",
         "TOOL_PREFIX": "projB",
         "PROJECT_NAME": "项目B",
         "API_DEBUG_ALLOWED_METHODS": "GET,POST,PUT,DELETE",
@@ -532,6 +555,72 @@ API 调试工具支持完整的登录认证流程，让您轻松管理 API 访
 
 这样设计让您无需手动管理认证状态，工具会自动处理登录和 token 更新，大大简化了 API 调试流程！
 
+### 7. 目录列表工具 (list_directory)
+递归地探索相对于项目根目录的目录结构。
+
+**参数：**
+- `path` (可选): 要列出的子目录路径。
+- `depth` (可选): 最大递归深度（默认：2）。
+
+**使用示例：**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 10,
+  "method": "tools/call",
+  "params": {
+    "name": "list_directory",
+    "arguments": {
+      "depth": 3
+    }
+  }
+}
+```
+
+### 8. 规则生成工具 (generate_cursorrules / generate_rules)
+根据您的标准生成 AI 项目指导文件（Cursor 使用 `.cursorrules`，其他客户端使用 `PROJECT_RULES.md`）。
+
+**参数：**
+- `save` (可选): 是否将内容保存到磁盘（默认：false）。
+
+**使用示例：**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 11,
+  "method": "tools/call",
+  "params": {
+    "name": "generate_cursorrules",
+    "arguments": {
+      "save": true
+    }
+  }
+}
+```
+
+### 9. 文件下载工具 (download_file)
+从指定的 URL 下载文件并保存到项目路径中的指定位置。
+
+**参数：**
+- `url` (必需): 要下载的文件的 URL。
+- `savePath` (必需): 文件保存路径（相对于项目路径或绝对路径）。
+
+**使用示例：**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 12,
+  "method": "tools/call",
+  "params": {
+    "name": "download_file",
+    "arguments": {
+      "url": "https://example.com/logo.png",
+      "savePath": "assets/logo.png"
+    }
+  }
+}
+```
+
 ## 🔗 相关工具协同使用
 
 为了提供更完整的开发体验，推荐与以下 MCP 工具协同使用：

package/bin/cli.js

@@ -3,7 +3,7 @@ const { spawn } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 
-// 简单日志输出
+// Simple log output
 const writeLog = (level, message, data = null) => {
   console.error(`[${level}] ${message}`);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liangshanli/mcp-server-project-standards",
-  "version": "3.0.2",
+  "version": "5.1.0",
   "description": "MCP Project Standards server with project info, structure, API standards, development standards, API debugging, login authentication and configuration management tools",
   "main": "bin/cli.js",
   "bin": {

package/src/server-final.js

@@ -12,16 +12,29 @@ const api_debug = require('./utils/api_debug');
 const api_config = require('./utils/api_config');
 const api_help = require('./utils/api_help');
 const api_execute = require('./utils/api_execute');
+const list_directory = require('./utils/list_directory');
+const generate_cursorrules = require('./utils/generate_cursorrules');
+const download_file = require('./utils/download_file');
 
 // Get config directory based on CONFIG_DIR and TOOL_PREFIX
 const getConfigDir = () => {
   let configDir = process.env.CONFIG_DIR;
+  // If PROJECT_PATH is null and client is Cursor, default to '.', otherwise null
+  const projectPath = process.env.PROJECT_PATH || (global.isCursor ? '.' : null);
+
   if (!configDir) {
     const toolPrefix = process.env.TOOL_PREFIX || '';
+    // Configuration location: under project path if available, otherwise current directory
+    const baseDir = projectPath || '.';
     if (toolPrefix) {
-      configDir = `./.setting.${toolPrefix}`;
+      configDir = path.resolve(baseDir, `.setting.${toolPrefix}`);
     } else {
-      configDir = './.setting';
+      configDir = path.resolve(baseDir, '.setting');
+    }
+  } else if (projectPath) {
+    // If CONFIG_DIR is set, make it absolute or relative to projectPath if not already absolute
+    if (!path.isAbsolute(configDir)) {
+      configDir = path.resolve(projectPath, configDir);
     }
   }
   return configDir;
@@ -62,40 +75,44 @@ const saveConfig = (config) => {
   }
 };
 
-// 启动日志
+// Startup logs
 console.error('=== MCP Project Standards Server Starting ===');
 console.error(`Time: ${new Date().toISOString()}`);
+console.error(`Project Path: ${process.env.PROJECT_PATH || '.'}`);
 console.error(`Config Dir: ${getConfigDir()}`);
 console.error('==============================================');
 
+// Global state
+global.isCursor = false;
+
 // Final MCP Server
 class ProjectStandardsMCPServer {
   constructor() {
     this.name = 'project-standards-mcp-server';
-    this.version = '1.2.2';
+    this.version = '5.1.0';
     this.initialized = false;
     this.config = getConfig();
     this.needsProjectFolder = this.config === null;
 
-    // 如果配置文件不存在，创建默认配置
+    // Create default config if config file doesn't exist
     if (this.needsProjectFolder) {
       this.createDefaultConfig();
     }
   }
 
-  // 创建默认配置文件
+  // Create default config file
   createDefaultConfig() {
     const configDir = getConfigDir();
     const configPath = path.join(configDir, 'config.json');
 
     try {
-      // 创建配置目录
+      // Create config directory
       if (!fs.existsSync(configDir)) {
         fs.mkdirSync(configDir, { recursive: true });
         console.error(`Created config directory: ${configDir}`);
       }
 
-      // 创建默认配置文件
+      // Create default config file
       const defaultConfig = {
         project_info: {},
         project_structure: [],
@@ -107,12 +124,12 @@ class ProjectStandardsMCPServer {
       fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2), 'utf8');
       console.error(`Created default config file: ${configPath}`);
 
-      // 更新配置和状态
+      // Update config and state
       this.config = defaultConfig;
       this.needsProjectFolder = false;
     } catch (err) {
       console.error('Failed to create default config:', err.message);
-      // 保持 needsProjectFolder = true 状态
+      // Keep needsProjectFolder = true state
     }
   }
 
@@ -197,8 +214,29 @@ class ProjectStandardsMCPServer {
     return result;
   }
 
+  // List directory tool
+  async list_directory(params) {
+    const result = await list_directory(params);
+    return result;
+  }
+
+  // Generate cursorrules tool
+  async generate_cursorrules(params) {
+    const result = await generate_cursorrules(params, this.config);
+    return result;
+  }
 
+  // Generate rules tool (for non-cursor)
+  async generate_rules(params) {
+    const result = await generate_cursorrules(params, this.config);
+    return result;
+  }
 
+  // Download file tool
+  async download_file(params) {
+    const result = await download_file(params);
+    return result;
+  }
 
   // Handle JSON-RPC requests
   async handleRequest(request) {
@@ -214,6 +252,11 @@ class ProjectStandardsMCPServer {
 
       try {
         if (method === 'initialize') {
+          // Detect Cursor client
+          const clientName = params?.clientInfo?.name || '';
+          global.isCursor = clientName.toLowerCase().includes('cursor');
+          console.error(`Client identified: ${clientName} (isCursor: ${global.isCursor})`);
+
           // If already initialized, return success but don't re-initialize
           if (!this.initialized) {
             this.initialized = true;
@@ -704,6 +747,26 @@ class ProjectStandardsMCPServer {
           }
         });
 
+        // Download File Tool
+        tools.push({
+          name: 'download_file',
+          description: 'Download a file from a URL and save it to a specified path. Supported schemes: http, https.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              url: {
+                type: 'string',
+                description: 'The URL of the file to download (required)'
+              },
+              savePath: {
+                type: 'string',
+                description: 'The path where the file should be saved (relative to project path or absolute, required)'
+              }
+            },
+            required: ['url', 'savePath']
+          }
+        });
+
           // API Config Tool
           tools.push({
             name: 'api_config',
@@ -878,6 +941,63 @@ class ProjectStandardsMCPServer {
             }
           });
 
+        // Check whether to show project structure related tools
+        const projectPath = process.env.PROJECT_PATH || (global.isCursor ? '.' : null);
+        const showStructureTools = !!projectPath;
+
+        if (showStructureTools) {
+          // List Directory Tool
+          tools.push({
+            name: 'list_directory',
+            description: 'List directory structure relative to the project path. Returns a tree of files and directories.',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                path: {
+                  type: 'string',
+                  description: 'Subdirectory path to list (relative to project path, optional)'
+                },
+                depth: {
+                  type: 'number',
+                  description: 'Max depth to traverse (default: 2, optional)'
+                }
+              }
+            }
+          });
+
+          if (global.isCursor) {
+            // Generate Cursor Rules Tool
+            tools.push({
+              name: 'generate_cursorrules',
+              description: 'Generate .cursorrules content based on project standards. Returns content and save path for user confirmation.',
+              inputSchema: {
+                type: 'object',
+                properties: {
+                  save: {
+                    type: 'boolean',
+                    description: 'Whether to save to .cursorrules file (default: false)'
+                  }
+                }
+              }
+            });
+          } else {
+            // Generate General Rules Tool
+            tools.push({
+              name: 'generate_rules',
+              description: 'Generate project rules content based on standards. Returns content and suggested save path for user confirmation.',
+              inputSchema: {
+                type: 'object',
+                properties: {
+                  save: {
+                    type: 'boolean',
+                    description: 'Whether to save to rules file (default: false)'
+                  }
+                }
+              }
+            });
+          }
+        }
+
           // Apply tool prefix and project name if both provided
           const toolPrefix = process.env.TOOL_PREFIX || '';
           const projectName = process.env.PROJECT_NAME || '';

package/src/utils/api_common.js

@@ -79,16 +79,16 @@ const getLoginMethod = () => {
 const getLoginBody = () => {
   const envBody = process.env.API_DEBUG_LOGIN_BODY || '{"username":"","password":""}';
   
-  // 如果是字符串格式，直接返回
+  // If it is a string format, return it directly
   if (typeof envBody === 'string' && !envBody.startsWith('{')) {
     return envBody;
   }
   
-  // 如果是JSON格式，解析后返回
+  // If it is JSON format, parse and return it
   try {
     return JSON.parse(envBody);
   } catch {
-    // 如果解析失败，返回原始字符串
+    // If parsing fails, return the original string
     return envBody;
   }
 };