Lspace

Lspace API と MCP サーバー

「本は時空を曲げます……Lspace には、危険を覚悟して迷い込んでください。」 - Terry Pratchett（Guards! Guards!）

Lspace を使えば、あらゆる AI セッションから得た知見を保存し、すべてのツールで即座に利用できるため、コンテキストの切り替えに伴う摩擦を解消できます。散在する会話を、永続的で検索可能なナレッジに変えます。

Lspace は、Model Context Protocol (MCP) を実装したオープンソースの API バックエンドおよびサーバーです。インテリジェントなナレッジベースの生成と管理機能をワークフローに統合し、AI エージェントやその他のツールを、管理対象のコンテンツリポジトリに接続できます。（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 サーバーのクローン、インストール、ビルド： 以下の手順で、MCP クライアントが実行できるよう Lspace サーバーのコードを準備します。

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 Tokens (PATs) について」のセクションをご覧ください。
     • repositories 配列で、Lspace が管理するローカルリポジトリまたは GitHub リポジトリを定義します。
     • 詳細な構造と例については、「リポジトリの手動管理（config.local.json）」セクションを参照してください。

D. MCP クライアントでの Lspace の設定： MCP クライアントが実行するのは、lspace-server ディレクトリ内の lspace-mcp-server.js スクリプトです。このスクリプトの場所と実行方法を 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 ファイルは自動的に読み込まれるはずです。
           // 環境変数を上書きする必要がある場合や、.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 で「Settings > Developer > Edit Config」を開くと作成されることがあります。

   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 Token（PAT）について

Lspace がユーザーに代わって GitHub リポジトリを操作するには、GitHub Personal Access Token（PAT）が必要です。これには、リポジトリのクローン、コンテンツの読み取り、そして重要な操作として、新しいコンテンツ（生成されたナレッジベースの記事や処理済みの未加工入力など）をコミットして変更をプッシュすることが含まれます。

PAT が必要な理由 PAT を使うと、パスワードを共有せずに、Lspace に GitHub アカウントへのアクセスを安全に許可できます。PAT ごとに付与する権限（スコープ）を管理でき、いつでも取り消せます。

Lspace 用 GitHub PAT の作成

1. GitHub の開発者設定に移動します。
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 スコープを選択する必要があります。このスコープを付与すると、パブリックリポジトリとプライベートリポジトリを完全に操作できます。 (説明用の画像リンクです。実際の UI は異なる場合があります。)
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 操作、検索、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 エンドポイント（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 Personal Access Token（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 ホスト型サービス（提供されている場合）を利用する必要があります。
• 各バージョンの公開日から 1 年後、そのバージョンのソフトウェアは自動的に、寛容なオープンソースライセンスである Apache License 2.0 に切り替わります。

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