Lspace Server

🚀 Lspace API & MCP Server

Lspaceは、任意のAIセッションから洞察をキャプチャし、すぐにすべてのツールで利用できるようにすることで、コンテキスト切り替えの摩擦を解消します。これにより、散らばった会話が持続的で検索可能な知識に変換されます。

"本は空間と時間を曲げます... あなたが危険を冒してLspaceに迷い込むことは自戒すべきです。" - Terry Pratchett (Guards! Guards!)

Lspaceは、Model Context Protocol (MCP) を実装したオープンソースのAPIバックエンドとサーバーです。開発者は、これを使用して、ワークフローにインテリジェントな知識ベースの生成と管理機能を統合し、AIエージェントや他のツールを管理されたコンテンツリポジトリに接続することができます。(MCPの詳細については、modelcontextprotocol.io を参照してください)。

包括的な技術ドキュメント、プロジェクトの詳細、およびLspaceを使用して構築された知識ベースの例については、公式のLspaceドキュメントリポジトリ を参照してください。

🚀 クイックスタート

このガイドでは、Lspaceサーバーのセットアップと、CursorやClaude DesktopなどのModel Context Protocol (MCP)クライアントでの使用方法について説明します。

前提条件

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を dist/ フォルダ内のJavaScriptにコンパイルします）。

npm run build

ビルド後、このディレクトリのルートにある lspace-mcp-server.js がMCPサーバーのメインスクリプトになります。

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 Tokens (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 Personal Access Tokens (PATs)の理解

Lspaceは、GitHubリポジトリとやり取りするためにGitHub Personal Access Tokens (PATs)が必要です。これには、リポジトリのクローン、コンテンツの読み取り、重要なことに、コミットとプッシュによる新しいコンテンツの書き込み（生成された知識ベース記事、処理された生入力など）が含まれます。

なぜPATsが必要なのか？

PATsは、パスワードを必要とせずにLspaceにGitHubアカウントへのアクセスを許可する安全な方法です。各PATに付与する権限（スコープ）を制御し、いつでも取り消すことができます。

Lspace用のGitHub PATの作成

1. GitHubの 開発者設定 にアクセスします。
2. [個人用アクセストークン] をクリックし、次に [トークン（クラシック）] をクリックします。より細かい制御が必要な場合は、[細粒度トークン] を探索することもできますが、この種のアプリケーションでは [トークン（クラシック）] の方が一般的に簡単です。
3. [新しいトークンの生成] をクリックし（次に [新しいトークン（クラシック）の生成] をクリックします）。
4. トークンに説明的な名前を付けます。たとえば、「lspace-server-access」など。
5. トークンの有効期限を設定します。
6. スコープの選択：Lspaceがリポジトリを完全に管理できるようにするには、読み取り、書き込み、コミット、およびプッシュを含め、repo スコープを選択する 必要があります。このスコープは、パブリックおよびプライベートリポジトリの完全な制御を付与します。 (説明用の画像リンク、実際のUIは異なる場合があります)
7. [トークンの生成] をクリックします。
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"
      }
      // 必要に応じて、異なるエイリアスでより多くのPATを追加できます
    ]
  },
  // ... リポジトリ設定の残りの部分 ...
}

✨ 主な機能

• セルフホスト可能なサービス：git操作、検索、およびLLM統合。
• Lspace MCPサーバー：lspace-mcp-server.js を介してModel Context Protocol (MCP)を実装し、AIエージェントや他のツールがLspaceの機能とプログラムでやり取りできるようにします。(MCPの詳細については、modelcontextprotocol.io を参照してください)。
• 複数リポジトリ管理：複数のgitプロバイダー（ローカル、GitHub）をサポート。
• AIオーケストレーション：自動文書分類、組織化、および要約。
• 知識ベース生成：リポジトリコンテンツのWikipediaのような合成を作成。
• 二重構造のリポジトリ：生のドキュメントと合成された知識ベース。
• タイムライン追跡：文書操作の追跡。
• 拡張可能なアーキテクチャ：カスタム統合用。

リポジトリ構造

Lspaceは二重構造のリポジトリアーキテクチャを利用しています。

1. 生のドキュメントストレージ (/.lspace/raw_inputs/)
   • ユーザーがアップロードした元のドキュメント、またはMCPサーバー/APIを介して取り込まれたドキュメント。
   • AIによるカテゴリ分けと組織化。
   • メタデータの強化と構造化されたフォーマット。
   • 操作は /.lspace/timeline.json で追跡されます。
2. 知識ベース合成（リポジトリルート）
   • 生のドキュメントからAIが生成したWikipediaのような構造。
   • エントリページ（通常はリポジトリルートの README.md）が概要を提供します。
   • 複数のドキュメントの情報を合成したトピックページ。
   • ソースドキュメントへの相互参照とリンク。

設定の詳細

クイックスタート以外に、設定に関する詳細は以下の通りです。

Lspace設定ファイル (config.local.json)

このファイルは、リポジトリの接続（ローカルパス、GitHubリポジトリの詳細）と資格情報（GitHub PATなど）を定義するために重要です。 その構造については、「手動でのリポジトリ管理 (config.local.json)」セクションを参照してください。

LLMプロンプト設定

文書処理と知識ベース生成のためのLLMをガイドするプロンプトは、src/config/prompts.ts に集約されています。これらを変更して、AIの動作をカスタマイズできます。

フルAPIサーバーの実行（オプション）

MCPサーバーに加えて、またはその代わりにRESTful APIエンドポイントが必要な場合（たとえば、ウェブアプリケーションの統合や直接の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 Personal Access Token (PAT) を持っていることを確認します。
2. credentials.github_pats セクションにPATを追加します（上記の例を参照）。
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ホストサービスを使用することができます（利用可能な場合）。
• 各バージョンの公開日から1年後、そのバージョンのソフトウェアは自動的にApache License 2.0（許容的なオープンソースライセンス）に変換されます。

完全なライセンステキストについては、リポジトリ内の LICENSE ファイルを参照してください。