Lspace Server

🚀 Lspace API と MCP サーバー

"本は空間と時間を曲げます… あなたが勝手に Lspace に迷い込むと危険です。" - テリー・プラチェット (『警備隊！警備隊！』)

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

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

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

🚀 クイックスタート

このガイドでは、Lspace サーバーのセットアップと、Cursor や Claude Desktop などのモデルコンテキストプロトコル (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 パーソナルアクセストークン (PAT) の理解」セクションを参照してください。
    - `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 をクローンしてビルドしたディレクトリの実際の絶対ファイルパスに置き換えてください。

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 を再起動してください。

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 パーソナルアクセストークン (PAT) の理解

Lspace は、あなたの代わりに GitHub リポジトリとやり取りするために、GitHub パーソナルアクセストークン (PAT) を必要とします。これには、リポジトリのクローン、コンテンツの読み取り、重要なことには、コミットとプッシュによる新しいコンテンツ (生成された知識ベースの記事、処理された生入力など) の書き込みなどの操作が含まれます。

なぜ PAT が必要なのか？

PAT は、パスワードを必要とせずに 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 を介してモデルコンテキストプロトコル (MCP) を実装し、AI エージェントや他のツールが Lspace の機能とプログラムでやり取りできるようにします。(MCP の詳細については、modelcontextprotocol.io を参照してください)
• 複数リポジトリ管理：複数の git プロバイダー (ローカル、GitHub) をサポート。
• AI オーケストレーション：自動化されたドキュメント分類、整理、および要約。
• 知識ベース生成：リポジトリコンテンツのウィキペディアのような合成を作成。
• 二重構造のリポジトリ：生のドキュメントと合成された知識ベース。
• タイムライン追跡：ドキュメント操作の追跡。
• 拡張可能なアーキテクチャ：カスタム統合用。

リポジトリ構造

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

生のドキュメントストレージ (/.lspace/raw_inputs/)

• ユーザーによってアップロードされた、または MCP サーバー/API を介して取り込まれた元のドキュメント。
• AI 支援による分類と整理。
• メタデータの強化と構造化されたフォーマット。
• /.lspace/timeline.json で操作が追跡されます。

知識ベース合成 (リポジトリルート)

• 生のドキュメントから AI 生成された、ウィキペディアのような構造。
• エントリページ (通常はリポジトリルートの README.md) が概要を提供します。
• 複数のドキュメントにまたがる情報を合成したトピックページ。
• ソースドキュメントへの相互参照とリンク。

設定の詳細

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

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

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

LLM プロンプト設定

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

フル API サーバーの実行 (オプション)

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. 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) の下でライセンスされています。

これは一般的に次のことを意味します。

• 個人プロジェクト、研究、および内部の非商用利用のために、ソフトウェアを自由に使用、変更、およびセルフホストすることができます。
• 商用利用 (たとえば、このソフトウェアを使用した有料サービスの提供) は制限されており、ロビン・スポティスウードから別の商用ライセンスが必要です。または、公式の Lspace Cloud ホストサービスを使用することができます (利用可能な場合)。
• 各バージョンの公開日から 1 年後、そのバージョンのソフトウェアは自動的に Apache License 2.0 (許容的なオープンソースライセンス) に変換されます。

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