Lspace Server

🚀 Lspace API & MCP Server

Lspace可消除上下文切换的摩擦，让你从任何AI会话中捕获见解，并立即让这些见解在所有工具中可用，将零散的对话转化为持久、可搜索的知识。它是一个开源的API后端和服务器，实现了模型上下文协议（MCP），使开发者能够将智能知识库生成和管理功能集成到其工作流程中，将AI代理和其他工具连接到托管的内容存储库。

🚀 快速开始

本指南将帮助你设置Lspace服务器，并将其配置为与模型上下文协议（MCP）客户端（如Cursor或Claude Desktop）一起使用。

一、前提条件

1. Node.js：建议使用LTS版本（包含npm），可从 nodejs.org 下载。
2. npm：随Node.js一起安装。
3. Git：可从 git-scm.com 下载。

二、克隆、安装和构建Lspace服务器

以下步骤将准备Lspace服务器代码，以便由MCP客户端执行。

1. 克隆Lspace服务器仓库：

git clone https://github.com/Lspace-io/lspace-server.git

2. 进入目录：

cd lspace-server

3. 安装依赖项：

npm install

4. 构建项目（将TypeScript编译为JavaScript，存于 dist/ 文件夹中）：

npm run build

构建完成后，MCP服务器的主脚本将是该目录根目录下的 lspace-mcp-server.js。

三、配置你的Lspace服务器

在MCP客户端能够使用Lspace之前，你需要对Lspace本身进行配置：

1. 环境变量（.env 文件）
   • 复制示例环境文件：

cp .env.example .env

- 编辑新的 `.env` 文件。
- **至关重要的是，设置你的 `OPENAI_API_KEY`**。
- 根据需要审查和调整其他变量（请参阅 `.env.example` 中的注释）。

2. Lspace存储库和凭证（config.local.json 文件）
   • 此文件告知Lspace要管理哪些存储库，并提供凭证（如GitHub个人访问令牌）。它不会提交到Git。
   • 复制示例配置文件：

cp config.example.json config.local.json

- 编辑 `config.local.json`：
    - 在 `credentials.github_pats` 下添加你的GitHub个人访问令牌。如果你需要有关创建个人访问令牌的详细说明，请参阅下面的 [了解Lspace的GitHub个人访问令牌（PATs）](#了解lspace的github个人访问令牌pats) 部分。
    - 在 `repositories` 数组下定义Lspace应管理的本地或GitHub存储库。
    - 有关详细结构和示例，请参阅“手动管理存储库（`config.local.json`）”部分。

四、在MCP客户端中配置Lspace

lspace-mcp-server.js 脚本（位于你的 lspace-server 目录中）是MCP客户端将执行的脚本。你需要告知MCP客户端如何找到并运行此脚本。

重要提示：在以下客户端配置中，将 /actual/absolute/path/to/your/lspace-server/ 替换为你克隆并构建 lspace-server 的目录的实际绝对文件路径。

1. Cursor Cursor可以通过JSON文件进行配置。你可以按项目或全局进行设置：
   • 项目配置：在项目的根目录下创建一个 .cursor/mcp.json 文件。
   • 全局配置：在用户主目录下创建一个 ~/.cursor/mcp.json 文件。

Cursor的 mcp.json 示例：

{
  "mcpServers": {
    "lspace-knowledge-base": { // 你可以在此处选择任何名称
      "command": "node",
      "args": ["/actual/absolute/path/to/your/lspace-server/lspace-mcp-server.js"],
      "env": {
        // lspace-server目录中的.env文件应会自动被拾取。
        // 仅当你需要专门为Cursor覆盖环境变量，或者未找到.env文件时，才在此处添加环境变量。
        // "OPENAI_API_KEY": "your_openai_key_if_not_in_lspace_env"
      }
    }
  }
}

- 请记住替换 `args` 中的占位符路径。
- 创建或修改此配置后，重启Cursor。

2. Claude Desktop Claude Desktop使用一个中央JSON配置文件：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\\Claude\\claude_desktop_config.json

如果此文件不存在，当你转到“设置”>“开发者”>“编辑配置”时，Claude Desktop可能会创建它。

claude_desktop_config.json 示例内容：

{
  "mcpServers": {
    "lspace": { // 你可以在此处选择任何名称
      "command": "node",
      "args": ["/actual/absolute/path/to/your/lspace-server/lspace-mcp-server.js"]
      // "env": { ... } // 与Cursor类似的环境变量考虑因素
    }
  }
}

- 确保你替换 `args` 中的占位符路径。
- 保存对此文件的更改后，重启Claude Desktop。

配置MCP客户端后，它应该能够启动并与你的Lspace服务器进行通信，从而允许你在客户端内使用Lspace工具并访问已配置的知识库。

了解Lspace的GitHub个人访问令牌（PATs）

Lspace需要GitHub个人访问令牌（PATs）来代表你与GitHub存储库进行交互。这包括克隆存储库、读取内容，以及重要的是，通过提交和推送更改来写入新内容（例如，生成的知识库文章、处理后的原始输入）等操作。

为什么需要PATs？

PATs是一种安全的方式，可在不需要你密码的情况下授予Lspace访问你的GitHub账户的权限。你可以控制授予每个PAT的权限（范围），并随时撤销它们。

为Lspace创建GitHub个人访问令牌

1. 转到你的GitHub 开发者设置。
2. 点击“个人访问令牌”，然后点击“令牌（经典）”。为了更精细的控制，你可以探索“细粒度令牌”，但“令牌（经典）”通常更适合此类应用程序。
3. 点击“生成新令牌”（然后点击“生成新令牌（经典）”）。
4. 为你的令牌提供一个描述性名称，例如 “lspace-server-access”。
5. 设置令牌的过期时间。
6. 选择范围：为了让Lspace完全管理你的存储库，包括读取、写入、提交和推送，你必须选择 repo 范围。此范围授予对公共和私有存储库的完全控制权。 (说明性图像链接，实际界面可能会有所不同)
7. 点击“生成令牌”。
8. 重要提示：立即复制生成的令牌。你将无法再次查看它。请安全地存储它。

在Lspace中使用PATs（config.local.json）

在你的 config.local.json 文件中，你将在 credentials.github_pats 部分为你的PAT定义一个 alias，然后在你的GitHub存储库配置中引用此 pat_alias。有关更多详细信息，请参阅“手动管理存储库（config.local.json）”部分。

config.local.json 中的示例 credentials 块：

{
  "credentials": {
    "github_pats": [
      {
        "alias": "my_lspace_pat",
        "token": "ghp_YOUR_COPIED_GITHUB_TOKEN_HERE"
      }
      // 如果需要，你可以添加更多具有不同别名的PATs
    ]
  },
  // ... 你的存储库配置的其余部分 ...
}

✨ 主要特性

• 可自托管服务：用于git操作、搜索和大语言模型集成。
• Lspace MCP服务器：通过 lspace-mcp-server.js 实现模型上下文协议（MCP），允许AI代理和其他工具以编程方式与Lspace功能进行交互。（有关MCP的更多信息，请参阅 modelcontextprotocol.io）。
• 多存储库管理：支持多个git提供商（本地、GitHub）。
• AI编排：用于自动文档分类、组织和总结。
• 知识库生成：用于创建类似维基百科的存储库内容综合。
• 双结构存储库：包含原始文档和综合知识库。
• 时间线跟踪：用于文档操作。
• 可扩展架构：用于自定义集成。

📚 详细文档

存储库结构

Lspace采用双结构存储库架构：

1. 原始文档存储（/.lspace/raw_inputs/）
   • 用户上传的原始文档或通过MCP服务器/API摄取的文档。
   • 借助AI进行分类和组织。
   • 元数据增强和结构化格式化。
   • 操作记录在 /.lspace/timeline.json 中。
2. 知识库综合（存储库根目录）
   • 由原始文档通过AI生成的类似维基百科的结构。
   • 一个入口页面（通常是存储库根目录中的 README.md）提供概述。
   • 主题页面综合多个文档中的信息。
   • 交叉引用和指向源文档的链接。

配置详情

除了快速开始部分，以下是更多配置细节：

1. Lspace配置文件（config.local.json） 此文件对于定义存储库连接（本地路径、GitHub存储库详细信息）和凭证（如GitHub PATs）至关重要。有关其结构，请参阅“手动管理存储库（config.local.json）”部分。
2. 大语言模型提示配置 指导大语言模型进行文档处理和知识库生成的提示集中在 src/config/prompts.ts 中。修改这些提示以自定义AI行为。

运行完整的API服务器（可选）

如果你除了MCP服务器之外还需要RESTful API端点（例如，用于Web应用程序集成或直接HTTP调用），或者替代MCP服务器：

1. 确保你的 .env 和 config.local.json 已按上述说明设置。
2. 构建项目：npm run build
3. 运行开发服务器：

npm run dev

4. 或者，进行生产部署：

npm start

这些脚本通常会启动 src/index.ts 中定义的完整应用程序，其中可能包括REST API和MCP功能。lspace-mcp-server.js 脚本是专门为仅MCP交互优化的入口点。

手动管理存储库（config.local.json）

你可以通过直接编辑本地的 config.local.json 文件来管理Lspace连接的存储库。此文件不会提交到版本控制（它在 .gitignore 中）。存储库中提供了一个示例模板 config.example.json。

请始终在 config.local.json 中进行更改。

该文件的基本结构包括一个 credentials 列表（用于GitHub等服务）和一个 repositories 列表。

{
  "credentials": {
    "github_pats": [
      {
        "alias": "your_github_pat_alias",
        "token": "ghp_yourgithubpersonalaccesstoken"
      }
    ]
  },
  "repositories": [
    {
      "name": "My Local Project",
      "type": "local",
      "path": "/path/to/your/local/git/repository",
      "path_to_kb": ".",
      "id": "your_unique_id_for_this_repo"
    },
    {
      "name": "My Awesome GitHub Project",
      "type": "github",
      "owner": "your-github-username-or-org",
      "repo": "your-repository-name",
      "branch": "main",
      "pat_alias": "your_github_pat_alias",
      "path_to_kb": ".",
      "id": "another_unique_id"
    }
  ]
}

添加本地存储库

1. 确保存储库是有效的Git存储库。
2. 在 config.local.json 的 repositories 数组中添加一个新对象（请参阅上述示例）。
   • name：一个人类可读的名称。
   • type：必须是 "local"。
   • path：你的本地Git存储库的绝对路径。
   • path_to_kb（可选）：存储库内知识库根目录的相对路径（例如，docs/kb）。默认为 .（存储库根目录）。
   • id（可选）：一个唯一的UUID。如果省略，将自动生成一个。

添加GitHub存储库

1. 确保你有一个具有 repo 范围的GitHub个人访问令牌（PAT）。
2. 将你的PAT添加到 credentials.github_pats 部分（请参阅上述示例）。
3. 在 repositories 数组中添加一个新对象（请参阅上述示例）。
   • name、type（"github"）、owner、repo、branch、pat_alias、path_to_kb、id 如上述说明。

编辑 config.local.json 后，重启Lspace MCP服务器或API服务器以使更改生效。Lspace将尝试将新的GitHub存储库克隆到 REPO_BASE_PATH 指定的目录（或其默认的 cloned-github-repos）中，并使所有配置的存储库可用。

📄 许可证

本项目采用商业源许可证1.1（BSL 1.1）授权。

这通常意味着：

• 你可以自由使用、修改和自托管该软件，用于个人项目、研究和内部非商业用途。
• 商业使用（例如，使用此软件提供付费服务）受到限制，需要从Robin Spottiswoode获得单独的商业许可证，或者使用官方的Lspace云托管服务（如果可用）。
• 每个版本公开发布日期起一年后，该版本的软件将自动转换为Apache许可证2.0，这是一个宽松的开源许可证。

有关完整的许可证文本，请参阅存储库中的 LICENSE 文件。