Lspace Server

Lspace Server

🚀 Lspace API 与 MCP 服务器

Lspace 可让你从任何 AI 会话中捕获见解,并立即在所有工具中使用这些见解,从而消除上下文切换的摩擦,将零散的对话转化为持久且可搜索的知识。

🚀 快速开始

本指南将帮助你设置 Lspace 服务器,并将其配置为与 Model Context Protocol (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
  1. 进入目录:
cd lspace-server
  1. 安装依赖项:
npm install
  1. 构建项目(将 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` 中的注释)。
  1. 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 个人访问令牌 (PAT)](#了解适用于-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。
  1. 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 的示例 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 PAT

  1. 访问你的 GitHub 开发者设置
  2. 点击“个人访问令牌”,然后点击“令牌(经典)”。为了获得更精细的控制,你可以探索“细粒度令牌”,但“令牌(经典)”通常更适合此类应用程序。
  3. 点击“生成新令牌”(然后点击“生成新令牌(经典)”)。
  4. 为你的令牌提供一个描述性名称,例如“lspace-server-access”。
  5. 设置令牌的过期时间。
  6. 选择范围:为了让 Lspace 全面管理你的仓库,包括读取、写入、提交和推送,你必须选择 repo 范围。此范围授予对公共和私有仓库的完全控制权。 GitHub PAT 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"
}
// 如果需要,你可以添加更多具有不同别名的 PAT
]
},
// ... 你的仓库配置的其余部分 ...
}

✨ 主要特性

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

📚 详细文档

仓库结构

Lspace 使用双结构仓库架构:

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

配置详情

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

Lspace 配置文件 (config.local.json)

此文件对于定义仓库连接(本地路径、GitHub 仓库详细信息)和凭证(如 GitHub PATs)至关重要。有关其结构,请参阅“手动管理仓库 (config.local.json)”部分。

大语言模型提示配置

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

运行完整的 API 服务器(可选)

如果你除了 MCP 服务器之外还需要 RESTful API 端点(例如,用于 Web 应用程序集成或直接 HTTP 调用),或者想替代 MCP 服务器使用:

  1. 确保你的 .envconfig.local.json 已按上述说明设置。
  2. 构建项目:npm run build
  3. 运行开发服务器:
npm run dev
  1. 或者,进行生产部署:
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.jsonrepositories 数组中添加一个新对象(见上文示例)。
    • name:一个人类可读的名称。
    • type:必须为 "local"
    • path:本地 Git 仓库的绝对路径。
    • path_to_kb(可选):仓库内知识库根目录的相对路径(例如,docs/kb)。默认为 .(仓库根目录)。
    • id(可选):一个唯一的 UUID。如果省略,将自动生成一个。

添加 GitHub 仓库

  1. 确保你有一个具有 repo 范围的 GitHub 个人访问令牌 (PAT)。
  2. 将你的 PAT 添加到 credentials.github_pats 部分(见上文示例)。
  3. repositories 数组中添加一个新对象(见上文示例)。
    • nametype"github")、ownerrepobranchpat_aliaspath_to_kbid 如上述说明。

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

📄 许可证

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

这通常意味着:

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

有关完整的许可证文本,请参阅仓库中的 LICENSE 文件。

  • 0 关注
  • 0 收藏,11 浏览
  • system 提出于 2025-09-20 13:39

相似服务问题