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:
- Node.js: LTS version recommended (includes npm). Download from nodejs.org.
- npm: Comes with Node.js.
- 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.
- Clone the Lspace server repository:
git clone https://github.com/Lspace-io/lspace-server.git - Navigate into the directory:
cd lspace-server - Install dependencies:
npm install - Build the project (compiles TypeScript to JavaScript in the
dist/folder):
The main script for the MCP server will benpm run buildlspace-mcp-server.jsin 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:
- Environment Variables (
.envfile):- Copy the example environment file:
cp .env.example .env - Edit the new
.envfile. - Crucially, set your
OPENAI_API_KEY. - Review and adjust other variables as needed (see comments in
.env.example).
- Copy the example environment file:
- Lspace Repositories & Credentials (
config.local.jsonfile):- 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
repositoriesarray. - Refer to the "Managing Repositories Manually (
config.local.json)" section for detailed structure and examples.
- Add your GitHub PATs under
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.
-
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.jsonin your project's root directory. - Global Configuration: Create a file at
~/.cursor/mcp.jsonin your user home directory.
Example
mcp.jsonfor 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.
- Project Configuration: Create a file at
-
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.jsoncontent:{ "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.
- macOS:
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:
- Go to your GitHub Developer settings.
- 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.
- Click "Generate new token" (and then "Generate new token (classic)").
- Give your token a descriptive name, like "lspace-server-access".
- Set an expiration period for the token.
- Select Scopes: For Lspace to fully manage your repositories, including reading, writing, committing, and pushing, you must select the
reposcope. This scope grants full control of public and private repositories.
(Illustrative image link, actual UI may vary) - Click "Generate token".
- 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:
- 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.
- Knowledge Base Synthesis (Repository Root):
- AI-generated, Wikipedia-like structure from raw documents.
- An entry page (typically
README.mdin 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:
- Ensure your
.envandconfig.local.jsonare set up as described above. - Build the project:
npm run build - Run the development server:
npm run dev - 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
- Ensure the repository is a valid Git repository.
- Add a new object to the
repositoriesarray inconfig.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
- Ensure you have a GitHub Personal Access Token (PAT) with
reposcope. - Add your PAT to the
credentials.github_patssection (see example above). - Add a new object to the
repositoriesarray (see example above).name,type("github"),owner,repo,branch,pat_alias,path_to_kb,idas 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.