Lspace

Lspace API 与 MCP 服务

“书籍会扭曲时空……误入 Lspace，后果自负。”——Terry Pratchett（《Guards! Guards!》）

Lspace 消除了上下文切换带来的阻碍，让你可以从任何 AI 会话中捕获见解，并立即在所有工具中使用这些见解——将零散的对话转化为持久、可搜索的知识。

Lspace 是一个实现了 Model Context Protocol (MCP) 的开源 API 后端和服务。它使开发者能够将智能知识库生成和管理功能集成到工作流中，并将 AI Agent 和其他工具连接到受管理的内容存储库。（关于 MCP 的更多信息，请参阅 modelcontextprotocol.io。）

如需全面的技术文档、项目详情，以及使用 Lspace 构建的知识库示例，请参阅 Lspace 官方文档仓库。

快速入门：在客户端中使用 Lspace MCP 服务

本指南将帮助你设置 Lspace 服务，并将其配置为与 Cursor 或 Claude Desktop 等 Model Context Protocol (MCP) 客户端配合使用。

A. 前置条件：

1. Node.js：推荐使用 LTS 版本（包含 npm）。请从 nodejs.org 下载。
2. npm：随 Node.js 一起提供。
3. Git：请从 git-scm.com 下载。

B. 克隆、安装并构建 Lspace 服务： 以下步骤将准备好 Lspace 服务代码，以便 MCP 客户端执行。

1. 克隆 Lspace 服务仓库：

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

2. 进入该目录：

   cd lspace-server
   

3. 安装依赖：

   npm install
   

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

   npm run build
   

   构建完成后，MCP 服务的主脚本将位于此目录的根目录下，文件名为 lspace-mcp-server.js。

C. 配置 Lspace 服务： MCP 客户端使用 Lspace 之前，你需要先配置 Lspace 本身：

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

     cp .env.example .env
     

   • 编辑新建的 .env 文件。
   • 务必设置你的 OPENAI_API_KEY。
   • 根据需要检查并调整其他变量（参阅 .env.example 中的注释）。
2. Lspace 仓库和凭据（config.local.json 文件）：
   • 此文件告知 Lspace 要管理哪些仓库，并提供凭据（例如 GitHub PAT）。此文件不会提交到 Git。
   • 复制示例配置文件：

     cp config.example.json config.local.json
     

   • 编辑 config.local.json：
     • 在 credentials.github_pats 下添加你的 GitHub PAT。如果需要创建 PAT 的详细说明，请参阅下方的了解 Lspace 的 GitHub Personal Access Token (PAT)部分。
     • 在 repositories 数组下定义 Lspace 应管理的本地或 GitHub 仓库。
     • 详细结构和示例请参阅“手动管理仓库（config.local.json）”部分。

D. 在 MCP 客户端中配置 Lspace： MCP 客户端将执行 lspace-mcp-server.js 脚本（位于你的 lspace-server 目录中）。你需要告知 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": { // You can choose any name here
         "command": "node",
         "args": ["/actual/absolute/path/to/your/lspace-server/lspace-mcp-server.js"],
         "env": {
           // .env file in lspace-server directory should be picked up automatically.
           // Only add environment variables here if you need to override them
           // specifically for Cursor, or if the .env file is not found.
           // "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 可能会在你前往 Settings > Developer > Edit Config 时创建该文件。

   claude_desktop_config.json 内容示例：

   {
     "mcpServers": {
       "lspace": { // You can choose any name here
         "command": "node",
         "args": ["/actual/absolute/path/to/your/lspace-server/lspace-mcp-server.js"]
         // "env": { ... } // Similar environment variable considerations as with Cursor
       }
     }
   }
   

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

配置 MCP 客户端后，它应该能够启动 Lspace 服务并与之通信，让你可以在客户端中使用 Lspace 工具并访问已配置的知识库。

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

Lspace 需要 GitHub 个人访问令牌（PAT），才能代表你与 GitHub 存储库交互。这包括克隆存储库、读取内容，以及尤为重要的写入新内容（例如，生成的知识库文章、处理后的原始输入），方法是提交并推送更改。

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

为 Lspace 创建 GitHub PAT：

1. 前往 GitHub Developer settings。
2. 点击“Personal access tokens”，然后点击“Tokens (classic)”。如需更精细的控制，你可以尝试“Fine-grained tokens”，但对于这类应用，“Tokens (classic)”通常更简单。
3. 点击“Generate new token”（然后点击“Generate new token (classic)”）。
4. 为令牌指定一个描述性名称，例如“lspace-server-access”。
5. 设置令牌的过期时间。
6. 选择权限范围：要让 Lspace 完全管理你的存储库，包括读取、写入、提交和推送，你必须选择 repo 权限范围。此权限范围授予对公开和私有存储库的完全控制权。 (示意图片链接，实际界面可能有所不同)
7. 点击“Generate token”。
8. 重要提示：立即复制生成的令牌。之后你将无法再次查看。请妥善保管。

在 Lspace 中使用 PAT（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"
      }
      // You can add more PATs with different aliases if needed
    ]
  },
  // ... rest of your repositories configuration ...
}

功能

• 可自托管的服务，用于 git 操作、搜索和大模型集成。
• Lspace MCP 服务：通过 lspace-mcp-server.js 实现模型上下文协议（MCP），让 AI Agent 和其他工具能够以编程方式使用 Lspace 的功能。（有关 MCP 的更多信息，请参阅 modelcontextprotocol.io。）
• 多存储库管理，支持多种 git 提供方（本地、GitHub）。
• AI 编排，用于自动执行文档分类、整理和摘要生成。
• 知识库生成，用于创建类似 Wikipedia 的存储库内容综合成果。
• 双结构存储库，包含原始文档和综合知识库。
• 时间线跟踪，用于记录文档操作。
• 可扩展架构，支持自定义集成。

存储库结构

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

1. 原始文档存储（/.lspace/raw_inputs/）：
   • 用户上传或通过 MCP 服务/API 导入的原始文档。
   • AI 辅助分类和整理。
   • 元数据增强和结构化格式处理。
   • 操作记录在 /.lspace/timeline.json 中。
2. 知识库综合整理（存储库根目录）：
   • 根据原始文档生成的、类似 Wikipedia 的结构。
   • 入口页面（通常是存储库根目录下的 README.md）提供概述。
   • 汇总多个文档信息的主题页面。
   • 指向源文档的交叉引用和链接。

配置详情

除快速入门外，以下是更多配置详情：

Lspace 配置文件（config.local.json）

此文件对于定义存储库连接（本地路径、GitHub 存储库详情）和凭据（如 GitHub PAT）至关重要。 有关其结构，请参阅“手动管理存储库（config.local.json）”部分。

大模型提示词配置

用于指导大模型处理文档和生成知识库的提示词集中存放在 src/config/prompts.ts 中。修改这些提示词即可自定义 AI 行为。

运行完整 API 服务（可选）

除了 MCP 服务，或替代 MCP 服务，如果你需要 RESTful API 端点（例如，用于集成 Web 应用或直接发起 HTTP 调用）：

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），并使所有已配置的代码库可用。

许可证

本项目采用 Business Source License 1.1（BSL 1.1）授权。

一般而言，这意味着：

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

完整许可证文本请参阅代码库中的 LICENSE 文件。