@liangshanli/mcp-server-project-standards 3.0.1 → 5.0.0

package/src/utils/generate_cursorrules.js

@@ -0,0 +1,172 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Generate rules content based on project standards
+ * @param {Object} params - Parameters
+ * @param {boolean} params.save - Whether to save to file (default: false)
+ * @param {Object} config - Server configuration
+ * @returns {Object} Content, savePath and status
+ */
+async function generate_cursorrules(params, config) {
+  const { save = false } = params || {};
+  const projectPath = process.env.PROJECT_PATH || (global.isCursor ? '.' : null);
+  
+  if (!projectPath) {
+    throw new Error('Rules generation is disabled: PROJECT_PATH is not set and client is not Cursor.');
+  }
+
+  if (!config) {
+    throw new Error('Configuration not found');
+  }
+
+  let rules = `---
+alwaysApply: true
+---
+
+# Project Standards and Rules
+
+## AI Assistant Guidelines
+You are an expert AI developer assistant. Your primary goal is to maintain and evolve this project while strictly adhering to the standards defined below.
+
+### Core Principles
+1. **Always Discover**: Before making changes, use \`list_directory\` and \`project_structure\` to understand the current context.
+2. **Follow Standards**: Consult \`api_standards\`, \`development_standards\`, and \`database_standards\` before implementing new logic.
+3. **API Integrity**: Use \`api_debug\` to test APIs and ensure they match the \`api_standards\`.
+4. **Consistency**: Match existing code patterns, naming conventions, and architectural styles.
+
+### MCP Tool Usage Workflow
+- **Information**: Use \`project_info\` to get/set high-level project metadata.
+- **Navigation**: Use \`list_directory\` (with depth) to explore the file system.
+- **Compliance**: Use \`api_standards\`, \`development_standards\`, and \`database_standards\` to get specific requirements.
+- **Testing**: Use \`api_debug\` for direct testing and \`api_execute\` for regression testing of configured APIs.
+- **Configuration**: Use \`api_config\` to manage the API list and base URLs.
+
+## MCP-Driven Project Standards Enforcement Rule
+
+### 1. Core Roles and Principles
+- **Role Positioning**: You are a Chief Architect strictly governed by the \`mcp-server-project-standards\` specifications.
+- **Supreme Principle**: **Tool Data > Documentation Content > Memory Hallucinations**. It is forbidden to assume project structure, API specifications, or development standards from memory without calling MCP tools.
+
+### 2. Mandatory Tool Call (Tool-First Policy)
+- **No Hard Reading of Long Documents**: When obtaining project specifications, architectural standards, or API definitions, **it is forbidden** to read full \`.md\` files in the \`docs/\` directory or long documents exceeding 100 lines.
+- **Mandatory Initialization**: When a conversation starts or a task switches, tools provided by \`mcp-server-project-standards\` (e.g., \`project_info\`, \`project_structure\`, \`api_standards\`) must be prioritized.
+- **Request on Demand**: Only apply to read specific file code snippets when the summary information returned by MCP tools is insufficient to support current code writing.
+
+### 3. Context Anti-Forgetfulness and Alignment Mechanism (Context Maintenance)
+- **Reread After Compression (Refresh Trigger)**: When you perceive that context is compressed (Summarized), conversations exceed 10 rounds, or project background becomes blurred, **you must proactively re-call** MCP tools to refresh the latest standard data.
+- **Confirmation Before Action**: Before executing refactoring or generating new modules, please declare: "Aligning project specifications via MCP..." and operate based on the results returned by the tools.
+- **Reject Deviation**: If the user's instructions violate the \`standards\` returned by MCP tools, be sure to point out the conflict points and provide correction plans that comply with the specifications.
+
+### 4. Token Consumption and Cost Optimization (Gemini 3 Flash Optimized)
+- **Cache-First Strategy**: Obtain short, structured results via MCP tools. This high-repetition short text can significantly trigger Gemini's Context Caching, reducing reading costs to $0.05/1M.
+- **Incremental Output**: Full rewriting is strictly prohibited. You must only output the affected code Diff or minimized code blocks (Output cost is $3/1M, must be streamlined).
+- **No Redundant Replies**: No need for polite language; directly output tool call results and code change suggestions.
+
+### 5. Automated Documentation Synchronization
+- **State Awareness**: After modifying core logic, you must ask whether to call MCP tools to synchronously update project standard descriptions or API snapshots, ensuring "code is the standard".
+
+## Dynamic MCP Tool Call Logic
+- **Project Identification**: Before executing any task, please first determine the current working sub-project path (e.g., \`./apps/user-service\`).
+- **Parameter Binding**: When calling tools of \`mcp-server-project-standards\`, the \`path\` or \`project_name\` parameters **must** be automatically bound to the currently detected sub-project.
+- **Tool Mapping Guidance**:
+  - To understand architectural layering -> Call \`project_structure\`
+  - To understand API interface standards -> Call \`api_standards\`
+  - To perform compliance checks -> Call \`development_standards\`
+- **Auto Alignment**: When the model finds that context is compressed or project background is lost, it must **force** a re-call of \`project_info\` and specify the current sub-project path to ensure that standards do not cross-project contaminate.
+
+## Context Management and Anti-Forgetfulness Mechanism
+- **Reread After Compression**: Whenever you (AI) perceive that context is compressed, conversation rounds are too many (e.g., more than 10), or "Context Drift" begins to appear, **you must proactively re-call** core tools of \`mcp-server-project-standards\` (e.g., \`project_info\`).
+- **Synchronization Declaration**: Before executing the first code generation after compression, please briefly declare at the beginning of the reply: "Project specification tools re-aligned" to ensure logical consistency.
+- **Mandatory Alignment**: Any time code is generated, if you are uncertain about the current API standards or structural standards due to context compression, you must first call tools to query; writing based on memory (hallucination) is strictly prohibited.
+
+`;
+
+  // Project Info
+  if (config.project_info) {
+    rules += `## Project Information\n`;
+    if (config.project_info.projectName) rules += `- **Project Name**: ${config.project_info.projectName}\n`;
+    if (config.project_info.developmentLanguage) rules += `- **Development Language**: ${config.project_info.developmentLanguage}\n`;
+    if (config.project_info.basicInfo) rules += `- **Basic Info**: ${config.project_info.basicInfo}\n`;
+    rules += `\n`;
+  }
+
+  // Project Structure
+  if (config.project_structure && config.project_structure.length > 0) {
+    rules += `## Project Structure\n`;
+    config.project_structure.forEach(item => {
+      rules += `- \`${item.path}\`: ${item.description}\n`;
+    });
+    rules += `\n`;
+  }
+
+  // API Standards
+  if (config.api_standards) {
+    rules += `## API Standards\n`;
+    if (config.api_standards.interfaceType) rules += `- **Interface Type**: ${config.api_standards.interfaceType}\n`;
+    if (config.api_standards.successStructure) rules += `- **Success Structure**: \`${config.api_standards.successStructure}\`\n`;
+    if (config.api_standards.errorStructure) rules += `- **Error Structure**: \`${config.api_standards.errorStructure}\`\n`;
+    
+    if (config.api_standards.requirements && config.api_standards.requirements.length > 0) {
+      rules += `### API Requirements\n`;
+      config.api_standards.requirements.forEach(req => {
+        rules += `- ${req}\n`;
+      });
+    }
+    rules += `\n`;
+  }
+
+  // Development Standards
+  if (config.development_standards && config.development_standards.length > 0) {
+    rules += `## Development Standards\n`;
+    config.development_standards.forEach(std => {
+      rules += `- ${std}\n`;
+    });
+    rules += `\n`;
+  }
+
+  // Database Standards
+  if (config.database_standards && config.database_standards.length > 0) {
+    rules += `## Database Standards\n`;
+    config.database_standards.forEach(std => {
+      rules += `- ${std}\n`;
+    });
+    rules += `\n`;
+  }
+
+  // Determine file name and path
+  const toolPrefix = process.env.TOOL_PREFIX || 'project';
+  const fileName = global.isCursor ? path.join('.cursor', 'rules', toolPrefix, 'RULE.md') : 'PROJECT_RULES.md';
+  const rulesPath = path.resolve(projectPath, fileName);
+
+  // System Metadata
+  rules += `## System Environment\n`;
+  rules += `- **Project Path**: \`${projectPath}\`\n`;
+  rules += `\n`;
+
+  if (save) {
+    try {
+      // Ensure directory exists
+      await fs.ensureDir(path.dirname(rulesPath));
+      await fs.writeFile(rulesPath, rules, 'utf8');
+      return {
+        success: true,
+        message: `${path.basename(rulesPath)} has been saved to ${rulesPath}`,
+        content: rules,
+        savePath: rulesPath
+      };
+    } catch (err) {
+      throw new Error(`Failed to save ${path.basename(rulesPath)}: ${err.message}`);
+    }
+  }
+
+  return {
+    success: true,
+    content: rules,
+    savePath: rulesPath,
+    suggestedFileName: fileName,
+    message: `Rules generated. Please review the content. You can call this tool with { "save": true } to save it to ${rulesPath}`
+  };
+}
+
+module.exports = generate_cursorrules;

package/src/utils/get_api_standards.js

@@ -23,7 +23,7 @@ async function api_standards(params, config, saveConfig) {
   
   if (action === 'get') {
     try {
-      // 从配置文件的 api_standards 字段中获取标准，如果没有则使用默认值
+      // Get standards from api_standards field in config file, use default if not present
       const apiStandards = config?.api_standards || {
         interfaceType: 'restful',
         successStructure: {
@@ -74,33 +74,33 @@ async function api_standards(params, config, saveConfig) {
     }
     
     try {
-      // 确保 config.api_standards 存在
+      // Ensure config.api_standards exists
       if (!config.api_standards) {
         config.api_standards = {};
       }
       
-      // 处理数组类型的合并逻辑
+      // Handle merging logic for array types
       if (Array.isArray(value) && !forceOverwrite) {
-        // 如果 forceOverwrite 为 false，则合并数组而不是覆盖
+        // Merge array instead of overwrite if forceOverwrite is false
         if (!config.api_standards[key]) {
           config.api_standards[key] = [];
         }
         
-        // 确保现有值是数组
+        // Ensure existing value is an array
         if (!Array.isArray(config.api_standards[key])) {
           config.api_standards[key] = [];
         }
         
-        // 合并数组，去重
+        // Merge array and remove duplicates
         const existingArray = config.api_standards[key];
         const newArray = [...new Set([...existingArray, ...value])];
         config.api_standards[key] = newArray;
       } else {
-        // 直接覆盖
+        // Overwrite directly
         config.api_standards[key] = value;
       }
       
-      // 保存配置
+      // Save configuration
       const saved = saveConfig(config);
       if (!saved) {
         throw new Error('Failed to save configuration');
@@ -131,23 +131,23 @@ async function api_standards(params, config, saveConfig) {
     }
     
     try {
-      // 确保 config.api_standards 存在
+      // Ensure config.api_standards exists
       if (!config.api_standards) {
         config.api_standards = {};
       }
       
-      // 删除 header
+      // Delete header
       if (headerName) {
-        // 确保 basicHeaders 存在
+        // Ensure basicHeaders exists
         if (!config.api_standards.basicHeaders) {
           config.api_standards.basicHeaders = {};
         }
         
-        // 删除指定的 header
+        // Delete specified header
         if (config.api_standards.basicHeaders.hasOwnProperty(headerName)) {
           delete config.api_standards.basicHeaders[headerName];
           
-          // 保存配置
+          // Save configuration
           const saved = saveConfig(config);
           if (!saved) {
             throw new Error('Failed to save configuration');
@@ -164,19 +164,19 @@ async function api_standards(params, config, saveConfig) {
         }
       }
       
-      // 删除 requirement
+      // Delete requirement
       if (requirement) {
-        // 确保 requirements 存在
+        // Ensure requirements exists
         if (!config.api_standards.requirements) {
           config.api_standards.requirements = [];
         }
         
-        // 查找并删除指定的 requirement
+        // Find and delete specified requirement
         const requirementIndex = config.api_standards.requirements.indexOf(requirement);
         if (requirementIndex !== -1) {
           config.api_standards.requirements.splice(requirementIndex, 1);
           
-          // 保存配置
+          // Save configuration
           const saved = saveConfig(config);
           if (!saved) {
             throw new Error('Failed to save configuration');

package/src/utils/get_development_standards.js

@@ -21,7 +21,7 @@ async function development_standards(params, config, saveConfig) {
   
   if (action === 'get') {
     try {
-      // 从配置文件的 development_standards 字段中获取标准，如果没有则使用默认值
+      // Get standards from development_standards field in config file, use default if not present
       const developmentStandards = config?.development_standards || [
         'Use 2 spaces for indentation',
         'Use single quotes instead of double quotes',
@@ -61,23 +61,23 @@ async function development_standards(params, config, saveConfig) {
     }
     
     try {
-      // 更新配置
+      // Update configuration
       if (!config.development_standards) {
         config.development_standards = [];
       }
       
-      // 处理数组类型的合并逻辑
+      // Handle merging logic for array types
       if (!forceOverwrite) {
-        // 如果 forceOverwrite 为 false，则合并数组而不是覆盖
+        // Merge array instead of overwrite if forceOverwrite is false
         const existingArray = config.development_standards;
         const newArray = [...new Set([...existingArray, ...standards])];
         config.development_standards = newArray;
       } else {
-        // 直接覆盖
+        // Overwrite directly
         config.development_standards = standards;
       }
       
-      // 保存配置
+      // Save configuration
       const saved = saveConfig(config);
       if (!saved) {
         throw new Error('Failed to save configuration');
@@ -103,17 +103,17 @@ async function development_standards(params, config, saveConfig) {
     }
     
     try {
-      // 确保 config.development_standards 存在
+      // Ensure config.development_standards exists
       if (!config.development_standards) {
         config.development_standards = [];
       }
       
-      // 查找并删除指定的 standard
+      // Find and delete specified standard
       const standardIndex = config.development_standards.indexOf(standard);
       if (standardIndex !== -1) {
         config.development_standards.splice(standardIndex, 1);
         
-        // 保存配置
+        // Save configuration
         const saved = saveConfig(config);
         if (!saved) {
           throw new Error('Failed to save configuration');

package/src/utils/get_project_info.js

@@ -20,20 +20,20 @@ async function project_info(params, config, saveConfig) {
   
   if (action === 'get') {
     try {
-      // 从配置文件的 project_info 字段中获取项目信息，如果没有则使用默认值
+      // Get project info from project_info field in config file, use default if not present
       const projectInfo = config?.project_info || '';
       const projectName = projectInfo.projectName || '';
       const developmentLanguage = projectInfo.developmentLanguage || '';
       const basicInfo = projectInfo.basicInfo || '';
 
       return {
-        // 项目名称
+        // Project name
         projectName: projectName,
         
-        // 开发语言
+        // Development language
         developmentLanguage: developmentLanguage,
         
-        // 基本信息
+        // Basic info
         basicInfo: basicInfo,
         
         timestamp: new Date().toISOString()
@@ -55,15 +55,15 @@ async function project_info(params, config, saveConfig) {
     }
     
     try {
-      // 确保 config.project_info 存在
+      // Ensure config.project_info exists
       if (!config.project_info) {
         config.project_info = {};
       }
       
-      // 更新指定字段
+      // Update specified field
       config.project_info[key] = value;
       
-      // 保存配置
+      // Save configuration
       const saved = saveConfig(config);
       if (!saved) {
         throw new Error('Failed to save configuration');

package/src/utils/get_project_structure.js

@@ -20,7 +20,7 @@ async function project_structure(params, config, saveConfig) {
   
   if (action === 'get') {
     try {
-      // 从配置文件的 project_structure 字段中获取结构，如果没有则使用默认值
+      // Get structure from project_structure field in config file, use default if not present
       const projectStructure = config?.project_structure || [];
 
       return projectStructure;
@@ -37,29 +37,29 @@ async function project_structure(params, config, saveConfig) {
     }
     
     try {
-      // 获取当前结构
+      // Get current structure
       let currentStructure = config?.project_structure || [];
       
-      // 创建新结构数组
+      // Create new structure array
       const newStructure = [];
       
-      // 循环处理每个新结构项
+      // Loop through each new structure item
       for (const item of structure) {
         if (!item.path || !item.description) {
           throw new Error('Each structure item must have "path" and "description" properties');
         }
         
-        // 检查路径是否已存在
+        // Check if path already exists
         const existingIndex = currentStructure.findIndex(existing => existing.path === item.path);
         
         if (existingIndex !== -1) {
-          // 路径存在，替换
+          // Path exists, replace
           currentStructure[existingIndex] = {
             path: item.path,
             description: item.description
           };
         } else {
-          // 路径不存在，添加到新结构
+          // Path doesn't exist, add to new structure
           newStructure.push({
             path: item.path,
             description: item.description
@@ -67,16 +67,16 @@ async function project_structure(params, config, saveConfig) {
         }
       }
       
-      // 将新结构附加到现有结构
+      // Append new structure to existing structure
       const updatedStructure = [...currentStructure, ...newStructure];
       
-      // 更新配置
+      // Update configuration
       if (!config.project_structure) {
         config.project_structure = [];
       }
       config.project_structure = updatedStructure;
       
-      // 保存配置
+      // Save configuration
       const saved = saveConfig(config);
       if (!saved) {
         throw new Error('Failed to save configuration');
@@ -103,17 +103,17 @@ async function project_structure(params, config, saveConfig) {
     }
     
     try {
-      // 确保 config.project_structure 存在
+      // Ensure config.project_structure exists
       if (!config.project_structure) {
         config.project_structure = [];
       }
       
-      // 查找并删除指定的路径
+      // Find and delete specified path
       const pathIndex = config.project_structure.findIndex(item => item.path === deletePath);
       if (pathIndex !== -1) {
         const deletedItem = config.project_structure.splice(pathIndex, 1)[0];
         
-        // 保存配置
+        // Save configuration
         const saved = saveConfig(config);
         if (!saved) {
           throw new Error('Failed to save configuration');

package/src/utils/list_directory.js

@@ -0,0 +1,85 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * List directory structure
+ * @param {Object} params - Parameters
+ * @param {string} params.path - Subdirectory path to list (relative to PROJECT_PATH)
+ * @param {number} params.depth - Max depth to traverse (default: 2)
+ * @returns {Object} Directory structure
+ */
+async function list_directory(params) {
+  const projectPath = process.env.PROJECT_PATH || (global.isCursor ? '.' : null);
+  
+  if (!projectPath) {
+    throw new Error('Project structure tool is disabled: PROJECT_PATH is not set and client is not Cursor.');
+  }
+
+  const subPath = params?.path || '';
+  const maxDepth = params?.depth || 2;
+  
+  const targetPath = path.resolve(projectPath, subPath);
+  
+  if (!targetPath.startsWith(path.resolve(projectPath))) {
+    throw new Error('Access denied: Path is outside of project directory');
+  }
+
+  if (!fs.existsSync(targetPath)) {
+    throw new Error(`Path does not exist: ${subPath}`);
+  }
+
+  const stats = fs.statSync(targetPath);
+  if (!stats.isDirectory()) {
+    return {
+      name: path.basename(targetPath),
+      type: 'file',
+      path: subPath
+    };
+  }
+
+  async function getTree(currentPath, currentRelativePath, currentDepth) {
+    const name = path.basename(currentPath);
+    const result = {
+      name: name || '.',
+      type: 'directory',
+      path: currentRelativePath,
+      children: []
+    };
+
+    if (currentDepth >= maxDepth) {
+      return result;
+    }
+
+    try {
+      const items = await fs.readdir(currentPath);
+      for (const item of items) {
+        // Skip hidden files/folders (starting with .)
+        if (item.startsWith('.') && item !== '.setting') continue;
+        if (item === 'node_modules') continue;
+
+        const itemPath = path.join(currentPath, item);
+        const itemRelativePath = path.join(currentRelativePath, item);
+        const itemStats = await fs.stat(itemPath);
+
+        if (itemStats.isDirectory()) {
+          result.children.push(await getTree(itemPath, itemRelativePath, currentDepth + 1));
+        } else {
+          result.children.push({
+            name: item,
+            type: 'file',
+            path: itemRelativePath
+          });
+        }
+      }
+    } catch (err) {
+      console.error(`Error reading directory ${currentPath}:`, err.message);
+    }
+
+    return result;
+  }
+
+  return await getTree(targetPath, subPath, 0);
+}
+
+module.exports = list_directory;
+