Lspace MCP Server

Instructions

Implementation Reference

• lspace-mcp-server.js:703-867 (handler)

  Main handler logic for 'lspace_browse_knowledge_base' tool in the callTool method. Validates parameters, syncs repository, performs list_directory or read_file operations via repository instance, and blocks write operations.

  case 'lspace_browse_knowledge_base':
    const { repositoryId: repoId2, operation, path, content: itemContent } = args;
    if (!repoId2 || !operation || !path) {
      return {
        jsonrpc: "2.0",
        id,
        error: {
          code: -32000,
          message: `Missing required parameters for lspace_browse_knowledge_base:\n` +
                  `• repositoryId: Get this from 'lspace_list_repositories'\n` +
                  `• operation: Use 'list_directory' or 'read_file'\n` +
                  `• path: Use '.' for root directory or 'folder/file.txt'\n\n` +
                  `Example: repositoryId='b3fcb584-5fd9-4098-83b8-8c5d773d86eb', operation='list_directory', path='.'`
        }
      };
    }
    
    if (!this.isInitialized || !this.repositoryManager) {
      return {
        jsonrpc: "2.0",
        id,
        error: {
          code: -32000,
          message: 'Repository manager not initialized'
        }
      };
    }
    
    // Normalize the path - if it's root ("/") or empty, use "." for repository root
    let normalizedPath = path;
    if (!normalizedPath || normalizedPath === '/' || normalizedPath === '') {
      normalizedPath = '.';
    }
    
    // Check for prohibited paths
    if (normalizedPath.includes('.lspace') || normalizedPath.includes('.git')) {
      return {
        jsonrpc: "2.0",
        id,
        error: {
          code: -32000,
          message: 'Operation on /.lspace/ or /.git/ directories is strictly prohibited'
        }
      };
    }
    
    try {
      // Get the repository configuration first
      const repoInfo = this.repositoryManager.getAllRepositoryConfigs().find(r => r.id === repoId2);
      
      if (!repoInfo) {
        return {
          jsonrpc: "2.0",
          id,
          error: {
            code: -32000,
            message: `Repository with ID ${repoId2} not found`
          }
        };
      }
      
      // Debug info before trying to access repository
      const debugInfo = {
        repositoryId: repoId2,
        configPath: repoInfo.path || 'N/A',
        repositoryType: repoInfo.type,
        originalPath: path || 'undefined',
        normalizedPath: normalizedPath,
        workingDir: process.cwd()
      };
      
      // Sync with remote before browsing (for GitHub repositories)
      try {
        await this.repositoryManager.syncWithRemote(repoId2);
      } catch (syncError) {
        console.warn(`Failed to sync repository before browsing: ${syncError.message}`);
        // Continue with browsing even if sync fails - user will see local version
      }
      
      // Get the repository instance
      const repository = this.repositoryManager.getRepository(repoId2);
      
      let result;
      switch (operation) {
        case 'list_directory':
          try {
            const items = await repository.listFiles(normalizedPath);
            result = {
              success: true,
              operation,
              path: normalizedPath,
              items: items,
              debug: debugInfo
            };
          } catch (listError) {
            // Return debug info even if listing fails
            result = {
              success: false,
              operation,
              error: listError.message,
              debug: debugInfo
            };
          }
          break;
          
        case 'read_file':
          const fileContent = await repository.readFile(path);
          result = {
            success: true,
            operation,
            path,
            content: fileContent
          };
          break;
          
        // Block all content creation/modification operations
        case 'create_file':
        case 'update_file':
        case 'delete_file':
        case 'create_directory':
        case 'delete_directory':
          return {
            jsonrpc: "2.0",
            id,
            error: {
              code: -32000,
              message: `❌ OPERATION BLOCKED: '${operation}' is not allowed in lspace_browse_knowledge_base.\n\n🚀 Use 'lspace_add_content' instead to:\n  • Add new content to the knowledge base\n  • Trigger automatic LLM processing\n  • Follow proper lspace workflow\n\nThe 'lspace_browse_knowledge_base' tool is READ-ONLY for browsing existing KB structure.`
            }
          };
          
        default:
          return {
            jsonrpc: "2.0",
            id,
            error: {
              code: -32000,
              message: `Unsupported operation: ${operation}`
            }
          };
      }
      
      return {
        jsonrpc: "2.0",
        id,
        result: {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2)
            }
          ]
        }
      };
      
    } catch (error) {
      return {
        jsonrpc: "2.0",
        id,
        error: {
          code: -32000,
          message: `Failed to ${operation}: ${error.message}`
        }
      };
    }

• lspace-mcp-server.js:216-238 (schema)

  Tool schema definition including inputSchema for parameter validation (repositoryId, operation, path) in the getTools() method.

  {
    name: "lspace_browse_knowledge_base",
    description: "📖 BROWSE: Read existing knowledge base files/directories (read-only). Automatically syncs with remote before browsing to ensure latest content. Example: To list files in 'Lspace Official Docs' root, use repositoryId='b3fcb584-5fd9-4098-83b8-8c5d773d86eb', operation='list_directory', path='.'",
    inputSchema: {
      type: "object",
      properties: {
        repositoryId: {
          type: "string",
          description: "The ID of the Lspace repository. Use 'lspace_list_repositories' first to get repository IDs."
        },
        operation: {
          type: "string", 
          description: "Operation type: 'list_directory' to see files/folders, 'read_file' to read file contents. Use 'lspace_add_content' for content creation.",
          enum: ["read_file", "list_directory"]
        },
        path: {
          type: "string",
          description: "Path relative to repository root. Use '.' for root directory, 'folder/file.txt' for specific files."
        }
      },
      required: ["repositoryId", "operation", "path"]
    }
  },

• lspace-mcp-server.js:351-357 (registration)

  Registration via 'tools/list' RPC method that returns the list of tools from getTools(), which includes 'lspace_browse_knowledge_base'.

  case 'tools/list':
    return {
      jsonrpc: "2.0",
      id,
      result: {
        tools: this.getTools()
      }