Lspace API & MCP Server

"Books bend space and time... You stray into Lspace at your peril." - Terry Pratchett (Guards! Guards!)

Lspace eliminates context-switching friction by letting you capture insights from any AI session and instantly make them available across all your tools - turning scattered conversations into persistent, searchable knowledge.

Lspace is an open-source API backend and server that implements the Model Context Protocol (MCP). It enables developers to integrate intelligent knowledge base generation and management capabilities into their workflows, connecting AI agents and other tools to managed content repositories. (See modelcontextprotocol.io for more on MCP).

For comprehensive technical documentation, project details, and an example of a knowledge base built with Lspace, please see the official Lspace documentation repository.

Quick Start: Using Lspace MCP Server with Clients

This guide helps you set up the Lspace server and configure it for use with Model Context Protocol (MCP) clients like Cursor or Claude Desktop.

A. Prerequisites:

1. Node.js: LTS version recommended (includes npm). Download from nodejs.org.
2. npm: Comes with Node.js.
3. Git: Download from git-scm.com.

B. Clone, Install & Build Lspace Server: These steps prepare the Lspace server code to be executed by an MCP client.

1. Clone the Lspace server repository:

   git clone https://github.com/Lspace-io/lspace-server.git
   

2. Navigate into the directory:

   cd lspace-server
   

3. Install dependencies:

   npm install
   

4. Build the project (compiles TypeScript to JavaScript in the dist/ folder):

   npm run build
   

   The main script for the MCP server will be lspace-mcp-server.js in the root of this directory after the build.

C. Configure Your Lspace Server: Before an MCP client can use Lspace, you need to configure Lspace itself:

1. Environment Variables (.env file):
   • Copy the example environment file:

     cp .env.example .env
     

   • Edit the new .env file.
   • Crucially, set your OPENAI_API_KEY.
   • Review and adjust other variables as needed (see comments in .env.example).
2. Lspace Repositories & Credentials (config.local.json file):
   • This file tells Lspace which repositories to manage and provides credentials (like GitHub PATs). It is not committed to Git.
   • Copy the example configuration file:

     cp config.example.json config.local.json
     

   • Edit config.local.json:
     • Add your GitHub PATs under credentials.github_pats. If you need detailed instructions on creating PATs, please see the Understanding GitHub Personal Access Tokens (PATs) for Lspace section below.
     • Define the local or GitHub repositories Lspace should manage under the repositories array.
     • Refer to the "Managing Repositories Manually (config.local.json)" section for detailed structure and examples.

D. Configuring Lspace in MCP Clients: The lspace-mcp-server.js script (in your lspace-server directory) is what MCP clients will execute. You need to tell your MCP client how to find and run this script.

Important: In the client configurations below, replace /actual/absolute/path/to/your/lspace-server/ with the real absolute file path to the directory where you cloned and built the lspace-server.

1. Cursor: Cursor can be configured via a JSON file. You can set this up per-project or globally:

   • Project Configuration: Create a file at .cursor/mcp.json in your project's root directory.
   • Global Configuration: Create a file at ~/.cursor/mcp.json in your user home directory.

   Example mcp.json for Cursor:

   {
     "mcpServers": {
       "lspace-knowledge-base": { // You can choose any name here
         "command": "node",
         "args": ["/actual/absolute/path/to/your/lspace-server/lspace-mcp-server.js"],
         "env": {
           // .env file in lspace-server directory should be picked up automatically.
           // Only add environment variables here if you need to override them
           // specifically for Cursor, or if the .env file is not found.
           // "OPENAI_API_KEY": "your_openai_key_if_not_in_lspace_env"
         }
       }
     }
   }
   

   • Remember to replace the placeholder path in args.
   • Restart Cursor after creating or modifying this configuration.

2. Claude Desktop: Claude Desktop uses a central JSON configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\\Claude\\claude_desktop_config.json

   If this file doesn't exist, Claude Desktop might create it when you go to Settings > Developer > Edit Config.

   Example claude_desktop_config.json content:

   {
     "mcpServers": {
       "lspace": { // You can choose any name here
         "command": "node",
         "args": ["/actual/absolute/path/to/your/lspace-server/lspace-mcp-server.js"]
         // "env": { ... } // Similar environment variable considerations as with Cursor
       }
     }
   }
   

   • Ensure you replace the placeholder path in args.
   • Restart Claude Desktop after saving changes to this file.

After configuring your MCP client, it should be able to start and communicate with your Lspace server, allowing you to use Lspace tools and access your configured knowledge bases from within the client.

Understanding GitHub Personal Access Tokens (PATs) for Lspace

Lspace requires GitHub Personal Access Tokens (PATs) to interact with your GitHub repositories on your behalf. This includes operations like cloning repositories, reading content, and importantly, writing new content (e.g., generated knowledge base articles, processed raw inputs) by committing and pushing changes.

Why PATs? PATs are a secure way to grant Lspace access to your GitHub account without needing your password. You can control the permissions (scopes) granted to each PAT and revoke them at any time.

Creating a GitHub PAT for Lspace:

1. Go to your GitHub Developer settings.
2. Click on "Personal access tokens" and then "Tokens (classic)". For finer-grained control, you might explore "Fine-grained tokens", but "Tokens (classic)" are generally simpler for this type of application.
3. Click "Generate new token" (and then "Generate new token (classic)").
4. Give your token a descriptive name, like "lspace-server-access".
5. Set an expiration period for the token.
6. Select Scopes: For Lspace to fully manage your repositories, including reading, writing, committing, and pushing, you must select the repo scope. This scope grants full control of public and private repositories. (Illustrative image link, actual UI may vary)
7. Click "Generate token".
8. Important: Copy the generated token immediately. You will not be able to see it again. Store it securely.

Using PATs in Lspace (config.local.json): In your config.local.json file, you'll define an alias for your PAT under the credentials.github_pats section and then reference this pat_alias in your GitHub repository configurations. See the "Managing Repositories Manually (config.local.json)" section for more details.

Example credentials block in config.local.json:

{
  "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 ...
}

Features

• Self-hostable service for git operations, search, and LLM integration.
• Lspace MCP Server: Implements the Model Context Protocol (MCP) via lspace-mcp-server.js, allowing AI agents and other tools to interact with Lspace capabilities programmatically. (See modelcontextprotocol.io for more on MCP).
• Multi-repository management with support for multiple git providers (local, GitHub).
• AI Orchestration for automated document classification, organization, and summarization.
• Knowledge Base Generation for creating a Wikipedia-like synthesis of repository content.
• Dual-structure repositories with raw documents and a synthesized knowledge base.
• Timeline tracking for document operations.
• Extensible architecture for custom integrations.

Repository Structure

Lspace utilizes a dual-structure repository architecture:

1. Raw Document Storage (/.lspace/raw_inputs/):
   • Original documents uploaded by users or ingested via the MCP server/API.
   • AI-assisted categorization and organization.
   • Metadata enhancement and structured formatting.
   • Operations tracked in /.lspace/timeline.json.
2. Knowledge Base Synthesis (Repository Root):
   • AI-generated, Wikipedia-like structure from raw documents.
   • An entry page (typically README.md in the repository root) provides an overview.
   • Topic pages synthesizing information across multiple documents.
   • Cross-references and links back to source documents.

Configuration Details

Beyond the Quick Start, here are more details on configuration:

Lspace Configuration File (config.local.json)

This file is critical for defining repository connections (local paths, GitHub repo details) and credentials (like GitHub PATs). See the "Managing Repositories Manually (config.local.json)" section for its structure.

LLM Prompts Configuration

Prompts guiding the LLM for document processing and knowledge base generation are centralized in src/config/prompts.ts. Modify these to customize AI behavior.

Running the Full API Server (Optional)

If you need the RESTful API endpoints (e.g., for web application integration or direct HTTP calls) in addition to or instead of the MCP server:

1. Ensure your .env and config.local.json are set up as described above.
2. Build the project: npm run build
3. Run the development server:

   npm run dev
   

4. Or, for a production deployment:

   npm start
   

These scripts typically start the full application defined in src/index.ts, which may include both REST API and MCP functionalities. The lspace-mcp-server.js script is a dedicated entry point optimized for MCP-only interactions.

Managing Repositories Manually (config.local.json)

You can manage the repositories Lspace connects to by directly editing your local config.local.json file. This file is not committed to version control (it's in .gitignore). An example template, config.example.json, is provided in the repository.

Always make your changes in config.local.json.

The basic structure of the file includes a list of credentials (for services like GitHub) and a list of 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"
    }
  ]
}

Adding a Local Repository

1. Ensure the repository is a valid Git repository.
2. Add a new object to the repositories array in config.local.json (see example above).
   • name: A human-readable name.
   • type: Must be "local".
   • path: The absolute path to your local Git repository.
   • path_to_kb (Optional): Relative path to the knowledge base root within the repo (e.g., docs/kb). Defaults to . (repository root).
   • id (Optional): A unique UUID. If omitted, one will be generated.

Adding a GitHub Repository

1. Ensure you have a GitHub Personal Access Token (PAT) with repo scope.
2. Add your PAT to the credentials.github_pats section (see example above).
3. Add a new object to the repositories array (see example above).
   • name, type ("github"), owner, repo, branch, pat_alias, path_to_kb, id as described.

After editing config.local.json, restart the Lspace MCP server or API server for changes to take effect. Lspace will then attempt to clone new GitHub repositories into the directory specified by REPO_BASE_PATH (or its default cloned-github-repos) and make all configured repositories available.

License

This project is licensed under the Business Source License 1.1 (BSL 1.1).

This generally means:

• You can freely use, modify, and self-host the software for personal projects, research, and internal non-commercial use.
• Commercial use (e.g., offering a paid service using this software) is restricted and requires a separate commercial license from Robin Spottiswoode, or use of an official Lspace Cloud hosted service (if available).
• After one (1) year from the public release date of each version, that version of the software will automatically convert to the Apache License 2.0, a permissive open-source license.

For the full license text, please see the LICENSE file in the repository.