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

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 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。

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 的示例 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 範圍。此範圍授予對公共和私有倉庫的完全控制權。 (說明性圖像鏈接，實際界面可能會有所不同)
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. 確保你的 .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 Cloud 託管服務（如果可用）。
• 每個版本從公開發布日期起一年後，該版本的軟件將自動轉換為 Apache 許可證 2.0，這是一個寬鬆的開源許可證。

有關完整的許可證文本，請參閱倉庫中的 LICENSE 文件。