From d1d60d165fe2276890042c17cabfeaa6ee3b9d7a Mon Sep 17 00:00:00 2001 From: Thiago Zanivan Date: Wed, 23 Jul 2025 14:54:12 -0300 Subject: [PATCH 1/6] ci: setup --- .github/workflows/build.yaml | 21 +++++++-------------- .github/workflows/release.yaml | 2 -- 2 files changed, 7 insertions(+), 16 deletions(-) diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index ef77922..97b5d21 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -14,26 +14,19 @@ jobs: build: runs-on: ubuntu-latest steps: - - name: Checkout code - uses: actions/checkout@v4 + - uses: actions/checkout@v4 - - name: Setup Bun - uses: oven-sh/setup-bun@v2 + - uses: oven-sh/setup-bun@v2 - - name: Cache dependencies - uses: actions/cache@v4 + - uses: actions/cache@v4 with: path: ~/.bun/install/cache key: bun-${{ hashFiles('**/bun.lockb') }} - - name: Install dependencies - run: bun install --frozen-lockfile + - run: bun install --frozen-lockfile - - name: Run linter - run: bun run lint + - run: bun run lint - - name: Run tests - run: bun test + - run: bun test - - name: Build project - run: bun run build + - run: bun run build diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index e569229..939567b 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -21,8 +21,6 @@ jobs: run: bun run build - name: Publish package - env: - NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }} run: | # Extract version from tag (remove 'v' prefix if present) VERSION=${GITHUB_REF_NAME#v} From 9768b65269fadf1f88e9eeb94a36a736a9cd174f Mon Sep 17 00:00:00 2001 From: Thiago Zanivan Date: Wed, 23 Jul 2025 15:06:28 -0300 Subject: [PATCH 2/6] fix: test environment --- .github/workflows/build.yaml | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 97b5d21..ef77922 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -14,19 +14,26 @@ jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - name: Checkout code + uses: actions/checkout@v4 - - uses: oven-sh/setup-bun@v2 + - name: Setup Bun + uses: oven-sh/setup-bun@v2 - - uses: actions/cache@v4 + - name: Cache dependencies + uses: actions/cache@v4 with: path: ~/.bun/install/cache key: bun-${{ hashFiles('**/bun.lockb') }} - - run: bun install --frozen-lockfile + - name: Install dependencies + run: bun install --frozen-lockfile - - run: bun run lint + - name: Run linter + run: bun run lint - - run: bun test + - name: Run tests + run: bun test - - run: bun run build + - name: Build project + run: bun run build From 888b20c1fb3d41c3bc821cc6e840cb9215d7071a Mon Sep 17 00:00:00 2001 From: Thiago Zanivan Date: Wed, 23 Jul 2025 15:12:56 -0300 Subject: [PATCH 3/6] fix: npm publish token --- .github/workflows/release.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 939567b..e569229 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -21,6 +21,8 @@ jobs: run: bun run build - name: Publish package + env: + NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }} run: | # Extract version from tag (remove 'v' prefix if present) VERSION=${GITHUB_REF_NAME#v} From 5b38ed47c0382bb4d875982ce514d2d8ad4dcc5e Mon Sep 17 00:00:00 2001 From: Thiago Zanivan Date: Wed, 23 Jul 2025 16:03:18 -0300 Subject: [PATCH 4/6] docs: how-to --- README.md | 303 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 297 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 33ec1be..6ab9b9e 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,306 @@ -# libcontext +# LibContext -To install dependencies: +**Local, Private, and AI-Ready Code Documentation Server** + +LibContext is a local-first, privacy-focused tool to build AI-friendly context for any library based on its documentation files — including private repositories. Extract, index, and serve documentation for AI coding assistants, IDEs, and LLM workflows. Get better results. + +--- + +## Overview + +LibContext MCP pulls up-to-date, version-specific, relevant documentation and code examples from a GitHub repository and places them into . + +Add `use libcontext` to your prompt in Cursor: + +``` +Add a collapsible sidebar shadcn to the base layout of the app. use shadcn-ui, use libcontext +``` + +LibContext fetches up-to-date code examples and documentation right into your LLM's context. + +1. Write your prompt +2. Tell the LLM to use LibContext +3. Get working code answers + +No tab-switching, no hallucinated APIs that don't exist, no outdated code generations. + +## How it works + +1. **Add a Library:** + Use the CLI to fetch documentation files (Markdown/MDX) from the specified repo/branch/tag/folders. + For private repos, supply a GitHub token. + +2. **AI Extraction:** + Each documentation file is processed by a LLM to extract code snippets, titles, and descriptions optimized for LLM retrieval. + +3. **Local Indexing:** + All extracted data is stored in a local libSQL database in your user data directory. + +4. **Query & Serve:** + Use the CLI to query docs/snippets, or start the MCP server to integrate with AI tools. + +## Features + +- **CLI:** Add, list and remove documentation of your tech stack using our CLI. +- **MCP Server:** Exposes a Model Context Protocol (MCP) server for integration with AI tools (Cursor, Windsurf, etc.). +- **Local and Private:** All data is stored locally using [libSQL](https://github.com/tursodatabase/libsql). No cloud or third-party storage required. +- **Customizable:** Choose which folders/files to index, and control which branches/tags to use. +- **Internal Library Support:** Add documentation from private GitHub repositories using a personal access token. +- **Cross-Platform:** Works on Linux, macOS, and Windows. + +--- + +## Installation + +You can install LibContext globally via npm: + +```bash +npm install -g libcontext +``` + +Or use it directly with `npx` (no installation required): + +```bash +npx -y libcontext +``` + +--- + +## Environment Setup + +**You must set the `OPENAI_API_KEY` environment variable for LibContext to work.** + +```bash +export OPENAI_API_KEY=sk-... +``` + +You can get your API key from [OpenAI's dashboard](https://platform.openai.com/api-keys). + +--- + +## Usage + +### CLI Overview + +All commands are available via the `libcontext` CLI (or `npx -y libcontext `). + +#### Add a Library + +Index documentation from a GitHub repository (public or private): + +```bash +libcontext add [--branch ] [--tag ] [--folders ...] [--token ] +``` + +- `--branch `: Git branch to index (default: repo default branch) +- `--tag `: Git tag to index (mutually exclusive with `--branch`) +- `--folders ...`: Only index documentation in these folders (default: all) +- `--token `: GitHub token for private repo access + +**Examples:** + +Add up-to-date LibContext documentation: + +```bash +libcontext add cozmo-dev/libcontext --branch main +``` + +Add documentation of a specific ShadCN UI version: + +```bash +libcontext add shadcn-ui/ui --tag shadcn-ui@0.9.4 +``` + +Add documentation of a private repo of your GitHub org: + +```bash +libcontext add myorg/myrepo --branch main --folders docs src/guides --token ghp_xxx +``` + +#### List Indexed Libraries + +```bash +libcontext list +``` + +#### Get Documentation + +Fetch up-to-date documentation for a library, optionally filtered by topic: ```bash -bun install +libcontext get [topic] [--k ] ``` -To run: +- `topic`: (optional) Focus on a specific topic (e.g., "hooks", "routing") +- `--k`: Number of top snippets to return (default: 10) + +**Example:** ```bash -bun run src/index.ts +libcontext get shadcn-ui/ui "Select" +``` + +#### Remove a Library + +```bash +libcontext rm +``` + +#### Start the MCP Server + +Expose the documentation server for AI tools (Cursor, Windsurf, etc.): + +```bash +libcontext start [--transport stdio|httpStream] [--port ] +``` + +- `--transport`: Communication method (`stdio` for local, `httpStream` for HTTP API, default: `stdio`) +- `--port`: Port for HTTP transport (default: 3000) + +--- + +## IDE & Tool Integration + +LibContext exposes a Model Context Protocol (MCP) server, making it easy to integrate with popular AI coding tools and IDEs. + +### Cursor + +Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` + +Pasting the following configuration into your Cursor `~/.cursor/mcp.json` file is the recommended approach. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info. + +```json +{ + "mcpServers": { + "libcontext": { + "command": "libcontext", + "args": ["start"], + "env": { + "OPENAI_API_KEY": "sk-..." + } + } + } +} +``` + +
+Alternative: Without global installation + +Or if you have not installed globally: + +```json +{ + "mcpServers": { + "libcontext": { + "command": "npx", + "args": ["-y", "libcontext", "start"], + "env": { + "OPENAI_API_KEY": "sk-..." + } + } + } +} ``` -This project was created using `bun init` in bun v1.2.2. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime. +
+ +
+Alternative: Using with Bun runtime + +```json +{ + "mcpServers": { + "libcontext": { + "command": "bunx", + "args": ["-y", "libcontext", "start"], + "env": { + "OPENAI_API_KEY": "sk-..." + } + } + } +} +``` + +
+ +### Windsurf + +Add this to your Windsurf MCP config file. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/mcp) for more info. + +```json +{ + "mcpServers": { + "libcontext": { + "command": "libcontext", + "args": ["start"], + "env": { + "OPENAI_API_KEY": "sk-..." + } + } + } +} +``` + +--- + +## Tips + +### Add a Rule + +> If you don’t want to add `use libcontext` to every prompt, you can define a simple rule in your `.windsurfrules` file in Windsurf or from `Cursor Settings > Rules` section in Cursor (or the equivalent in your MCP client) to auto-invoke LibContext on any code-related question: +> +> ```toml +> [[calls]] +> match = "when the user requests code examples, setup or configuration steps, or library/API documentation" +> tool = "libcontext" +> ``` +> +> From then on you’ll get LibContext’s docs in any related conversation without typing anything extra. You can add your use cases to the match part. + +--- + +## Data Storage + +- **Database:** + Uses your OS's standard data directory (e.g., `~/.local/share/libcontext/libcontext.db` on Linux). +- **No Cloud:** + All data remains on your machine unless you explicitly share it. + +--- + +## Security & Privacy + +- **Private by Default:** + No data leaves your machine. +- **Private Repo Support:** + Your GitHub token is only used locally to fetch documentation. + +--- + +## Contributing + +- **Run in development mode:** + ```bash + bun dev + ``` + +--- + +## Troubleshooting + +- **Permission Errors:** + Ensure the data directory is writable (see error message for path). +- **Private Repo Issues:** + Double-check your GitHub token and repo access. +- **OpenAI Errors:** + Ensure your `OPENAI_API_KEY` environment variable is set. + +--- + +## License + +MIT + +--- + +**Build your own private, AI-ready documentation server—locally.** From a6d54162addecb060acbf56e483ca54f0a5b3c41 Mon Sep 17 00:00:00 2001 From: Thiago Zanivan Date: Wed, 23 Jul 2025 16:29:30 -0300 Subject: [PATCH 5/6] chore: typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6ab9b9e..5188602 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ LibContext is a local-first, privacy-focused tool to build AI-friendly context f ## Overview -LibContext MCP pulls up-to-date, version-specific, relevant documentation and code examples from a GitHub repository and places them into . +LibContext MCP pulls up-to-date, version-specific, relevant documentation and code examples from a GitHub repository and makes it available to your IDE. Add `use libcontext` to your prompt in Cursor: From bdfe86fe2699d01e71755daf69980f711db2f305 Mon Sep 17 00:00:00 2001 From: Thiago Zanivan Date: Wed, 23 Jul 2025 16:33:44 -0300 Subject: [PATCH 6/6] docs: add note about OpenAI use Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5188602..40a4c1e 100644 --- a/README.md +++ b/README.md @@ -271,10 +271,11 @@ Add this to your Windsurf MCP config file. See [Windsurf MCP docs](https://docs. ## Security & Privacy - **Private by Default:** - No data leaves your machine. + All indexes are stored locally. + ⚠️ During the *AI Extraction* step the selected documentation is sent to the OpenAI API (or whichever LLM you configure). + If you need zero-egress processing, self-host the model or disable extraction. - **Private Repo Support:** Your GitHub token is only used locally to fetch documentation. - --- ## Contributing