# Local Knowledge MCP

A security-first, read-only [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for local folders.

Local Knowledge MCP lets an MCP client browse an explicit root allowlist, inspect metadata, read bounded text, and receive supported images and documents as MCP content. It is intentionally not a general-purpose filesystem write server.

## Features

- Read-only by design and default-deny.
- Client paths use `root_alias + relative path`; clients never send local absolute paths.
- Blocks unknown roots, parent traversal, symlink escape, hidden paths, and common secret-bearing files.
- Atomically updates the persistent root configuration.
- Reloads the security policy on every tool call, so `lk-add`, `lk-remove`, and `lk-clear` take effect without a project-specific runtime manager.
- Ships as a normal Python package with portable console commands.
- Provides guided ChatGPT setup through OpenAI Secure MCP Tunnel without bundling shared tunnel identities or credentials.

## Requirements

- Python 3.11 or newer.
- [`uv`](https://docs.astral.sh/uv/) is recommended; `pipx` also works.
- For local stdio usage: an MCP client that can launch a local process.
- For ChatGPT usage: OpenAI tunnel permissions and ChatGPT developer-mode access. `lk-chatgpt-setup` guides this optional flow.

## Install

### Directly from GitHub

With uv:

```bash
uv tool install "git+https://github.com/TuanLe-bk18/local-knowledge-mcp.git"
```

Or with `pipx`:

```bash
pipx install "git+https://github.com/TuanLe-bk18/local-knowledge-mcp.git"
```

### From a clone

```bash
git clone https://github.com/TuanLe-bk18/local-knowledge-mcp.git
cd local-knowledge-mcp
uv tool install .
```

The installation provides:

```text
local-knowledge-mcp
lk-init
lk-set
lk-add
lk-list
lk-remove
lk-clear
lk-chatgpt-setup
```

## Update

If installed directly from GitHub with `uv`, refresh and reinstall the tool from the latest commit:

```bash
uv tool upgrade local-knowledge-mcp --reinstall
```

If installed with `pipx`:

```bash
pipx install --force "git+https://github.com/TuanLe-bk18/local-knowledge-mcp.git@main"
```

For an installation made from a local clone:

```bash
git pull --ff-only origin main
uv tool install --force --reinstall .
```

Restart or reconnect local MCP clients after upgrading. For a managed ChatGPT tunnel runtime, recreate it with the updated executable:

```bash
lk-chatgpt-setup --no-browser
```

The existing root configuration, tunnel ID, and runtime key file are reused.

## Quick start

Initialize a secure empty configuration:

```bash
lk-init
```

Add one or more allowed folders:

```bash
lk-add project "~/Code/my-project"
lk-add notes "~/Documents/notes"
lk-list
```

### Connect a local stdio MCP client

`lk-init` prints an MCP client configuration using the installed executable. A typical configuration is:

```json
{
  "mcpServers": {
    "local-knowledge": {
      "command": "local-knowledge-mcp"
    }
  }
}
```

Some desktop applications do not inherit your shell `PATH`. In that case, use the absolute command path printed by `lk-init`.

Restart or reconnect the MCP client after first adding the server. Root allowlist changes made while the server is running are loaded automatically on the next tool call.

See [`docs/client-setup.md`](docs/client-setup.md) for local stdio setup details and troubleshooting.

### Connect ChatGPT with Secure MCP Tunnel

After configuring at least one root, run:

```bash
lk-chatgpt-setup
```

The command:

1. discovers `tunnel-client`, or offers to download the latest official [`openai/tunnel-client`](https://github.com/openai/tunnel-client) release;
2. verifies the downloaded archive against the official `SHA256SUMS.txt` asset;
3. opens OpenAI Platform tunnel and runtime-key setup pages;
4. asks for the user's own `tunnel_id` and hidden runtime API key;
5. stores the runtime key outside the repository in a user-private `0600` file;
6. starts a managed tunnel runtime and waits until it reports `ready`;
7. opens ChatGPT connector settings and prints the tunnel ID to select or paste.

The runtime key must have Tunnels **Read + Use**. An admin key is not accepted, stored, or passed to the long-lived runtime. Tunnel creation remains in the authenticated OpenAI Platform UI, so every installation uses the user's own tunnel identity and permissions.

See [`docs/chatgpt-setup.md`](docs/chatgpt-setup.md) for prerequisites, non-interactive options, credential storage, and troubleshooting.

## Root commands

Replace every configured root with one `workspace` root:

```bash
lk-set "/path/to/folder"
```

Add or update an alias while preserving other roots:

```bash
lk-add project "/path/to/project"
```

List roots without touching the MCP process:

```bash
lk-list
```

Remove one alias:

```bash
lk-remove project
```

Remove all roots while keeping read-only/default-deny policy enabled:

```bash
lk-clear
```

Folder inputs are expanded, required to exist, required to be directories, and saved as canonical absolute paths. Aliases must begin with a lowercase letter and may contain lowercase letters, numbers, hyphens, and underscores.

The persistent configuration is stored outside the repository at:

```text
~/.config/local-knowledge-mcp/security.yaml
```

No personal root configuration is bundled in the package.

## MCP tools

```text
browse(root_alias, path="")
get_info(root_alias, path)
read_text(root_alias, path, max_chars=None)
read_document_resource(root_alias, path)
read_file_resource(root_alias, path)
```

Example tool arguments:

```json
{
  "root_alias": "project",
  "path": "docs/architecture.md"
}
```

`read_file_resource` returns PNG, JPEG, and GIF files as concise text metadata plus MCP `ImageContent`, with structured output disabled so clients can pass them to a model's image input without duplicating base64 as text. It returns allowed PDF, DOCX, PPTX, XLSX, and XLS files as `EmbeddedResource` values. It does not parse, OCR, index, or modify files. The existing `read_document_resource` tool remains available for PDF/XLSX compatibility.

## Security model

Every filesystem access reaches `SecurityPolicy.resolve()` before touching a client-selected path. The default generated policy enforces:

```yaml
mode:
  read_only: true
  default_deny: true

path_policy:
  allow_absolute_paths_from_client: false
  allow_parent_traversal: false
  allow_symlinks: false
  allow_hidden_files: false
```

Additional deny patterns block common credential, token, key, environment, build, and VCS paths. Direct text reads are UTF-8 only, extension-limited, binary-checked, file-size limited, and character-limited.

An empty root mapping is valid and denies every root alias. See [`SECURITY.md`](SECURITY.md) before changing policy defaults.

## Scope

Included:

- directory browsing;
- file/directory metadata;
- bounded text/source reading;
- PNG/JPEG/GIF image content and PDF/DOCX/PPTX/XLSX/XLS embedded resources;
- local root allowlist management.

Not included:

- write, edit, delete, move, or create operations;
- arbitrary absolute-path access;
- OCR or document parsing;
- embeddings, vector databases, or RAG;
- a shared hosted tunnel, shared runtime credential, or shared cloud runtime.

For ChatGPT, `lk-chatgpt-setup` configures the official outbound Secure MCP Tunnel client on the user's machine. This repository never bundles tunnel credentials, identifiers, API keys, or machine-specific runtime state.

## Development

```bash
git clone https://github.com/TuanLe-bk18/local-knowledge-mcp.git
cd local-knowledge-mcp
uv sync --all-groups
uv run pytest -q
uv build
```

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for contribution guidelines.