# Company KB MCP

Company KB MCP is a local-first Model Context Protocol server that lets AI coding assistants search company Markdown
knowledge stored in GitLab repositories.

It is designed for GitHub Copilot and Claude Code. The server clones selected GitLab repositories into a local cache,
indexes Markdown and MDX files into a local SQLite database, and exposes MCP tools for search, cited answers, document
opening, repository sync, and repository removal.

The server is read-only. It does not write to GitLab, push commits, create branches, or update source files.

## What It Does

- Adds GitLab repositories by URL.
- Clones or refreshes shallow local repository mirrors.
- Indexes Markdown, MDX, README, docs, ADR, runbook, and playbook content.
- Stores repository, document, chunk, and keyword-search data in SQLite.
- Optionally stores local vector embeddings with `sqlite-vec` and FastEmbed.
- Returns snippets with GitLab source metadata and canonical source URLs.
- Redacts secret-looking values from logs and tool responses.

## How It Works

1. A user installs the MCP from the private marketplace.
2. GitHub Copilot or Claude Code starts the MCP server over stdio.
3. The user asks the assistant to add a GitLab repository.
4. The MCP server resolves the GitLab project, clones it locally, and indexes Markdown files.
5. Later questions use local keyword search, optional semantic search, or both.
6. The assistant receives cited evidence and uses it to answer the user.

The local index stays on the user's machine. Private repositories require the user to provide a GitLab token through an
environment variable.

## Install From Private Marketplace

The exact marketplace URL and package registry details are placeholders for now.

### GitHub Copilot

1. Open the private plugin marketplace.
2. Search for `Company KB`.
3. Install the GitHub Copilot target.
4. If prompted, provide a GitLab token secret named `GITLAB_TOKEN`.
5. Restart or reload the IDE MCP tools.

Expected MCP configuration shape:

```json
{
  "servers": {
    "company-kb": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "company-kb-mcp==0.1.0", "company-kb-mcp", "serve"]
    }
  }
}
```

### Claude Code

1. Open the private plugin marketplace.
2. Search for `Company KB`.
3. Install the Claude Code target, or run the marketplace-generated install command.
4. Set `GITLAB_TOKEN` in your shell if you need private repository access.
5. Start or reload Claude Code and run `/mcp` to confirm the server is connected.

Expected Claude Code command shape:

```bash
claude mcp add-json --scope user company-kb \
  '{"type":"stdio","command":"uvx","args":["--from","company-kb-mcp==0.1.0","company-kb-mcp","serve"],"env":{"GITLAB_TOKEN":"${GITLAB_TOKEN:-}"}}'
```

## Basic Usage

After installation, ask your assistant to add a repository:

```text
Use company-kb to sync https://gitlab.com/gitlab-org/cli
```

Then ask questions that need company documentation:

```text
Search company-kb for the deployment runbook for the billing service.
```

```text
Use company-kb to answer with citations: how do we rotate production credentials?
```

Useful actions:

- Add a repository: call `company_kb_sync_repository` with a GitLab URL.
- Refresh known repositories: call `company_kb_sync`.
- List indexed repositories: call `company_kb_list_repositories`.
- Search documentation: call `company_kb_search`.
- Open exact source context: call `company_kb_open_doc`.
- Build a cited evidence pack: call `company_kb_answer`.
- Remove a repository from the local index: call `company_kb_remove_repository`.

## Configuration

Configuration is optional for ad hoc usage. Without a config file, repositories can still be added by URL.

Common environment variables:

- `GITLAB_TOKEN`: optional token for private GitLab repositories.
- `COMPANY_KB_CONFIG`: optional path to a YAML config file.
- `COMPANY_KB_CACHE_DIR`: optional local repository cache directory.
- `COMPANY_KB_DATA_DIR`: optional local SQLite index directory.
- `COMPANY_KB_LOG_FILE`: optional JSONL log file path.
- `COMPANY_KB_AUTO_SYNC_ON_STARTUP`: set to `1` to refresh indexed repositories when the server starts.

For private GitLab repositories, the token needs:

- `read_api`
- `read_repository`

Do not put token values in marketplace metadata, MCP config files, plugin manifests, or checked-in YAML files.

## Local Development

Requirements:

- Python 3.11 or newer.
- `uv`.
- Git 2.30 or newer.

Install dependencies:

```bash
uv sync --dev
```

Start the MCP server:

```bash
uv run company-kb-mcp serve
```

Run tests:

```bash
uv run pytest
```

Run a local sync from the CLI:

```bash
uv run company-kb-mcp sync-url --url https://gitlab.com/gitlab-org/cli
```

Check status:

```bash
uv run company-kb-mcp status
```

## Architecture

See [ARCHITECTURE.md](ARCHITECTURE.md) for the component map and sequence diagrams.

## Current Limits

- Group discovery is scaffolded, but explicit repository URL sync is the main path.
- Production keychain and OAuth auth modes are not implemented in the Python MVP.
- `company_kb_open_doc` reads the current local cache; it does not check out historical commits.
- Semantic search is optional and may download local FastEmbed model files on first use.