Metadata-Version: 2.4
Name: ai-kb-mcp
Version: 1.1.2
Summary: AI KB MCP Server - Model Context Protocol server for AI KB API
Home-page: https://github.com/jrmatherly/ai-kb/tree/main/mcp-server
Author: AI KB Team
Author-email: AI KB Team <support@matherly.net>
Maintainer-email: AI KB Team <support@matherly.net>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jrmatherly/ai-kb
Project-URL: Documentation, https://ai-kb-docs.matherly.net
Project-URL: Repository, https://github.com/jrmatherly/ai-kb/tree/main/mcp-server
Project-URL: Bug Reports, https://github.com/jrmatherly/ai-kb/issues
Project-URL: Changelog, https://github.com/jrmatherly/ai-kb/blob/main/mcp-server/CHANGELOG.md
Keywords: mcp,model-context-protocol,aikb,knowledge-management,api-server
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<3,>=2
Requires-Dist: requests>=2.33.0
Requires-Dist: starlette>=1.3.1
Requires-Dist: uvicorn>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# AI KB MCP Server

> **⚠️ Deprecated**
>
> AI KB now ships a built-in MCP server: create endpoints under "Settings → Publish & Integrations → MCP Server", each with its own token, knowledge-base scope and tool list, and connect clients to `/mcp/<endpoint_id>` over Streamable HTTP. Prefer the built-in endpoint; this Python package may be removed in a future release.

A Model Context Protocol (MCP) server that gives access to the AI KB knowledge management API.

## Quick start

> We recommend following the [MCP configuration guide](https://github.com/jrmatherly/ai-kb/blob/main/mcp-server/MCP_CONFIG.md) instead of the steps below.

### 1. Install

```bash
pip install ai-kb-mcp
# Or run it with uvx without installing
uvx --from ai-kb-mcp ai-kb-mcp-server
```

The distribution is **`ai-kb-mcp`**; its command-line entry points are `ai-kb-mcp-server` and `ai-kb-server`.
The MCP packages on PyPI under the upstream project's name belong to that project and read its own variable names, not `AIKB_*`.

### 2. Set environment variables

```bash
# Linux/macOS
export AIKB_BASE_URL="http://localhost:8080/api/v1"
export AIKB_API_KEY="your_api_key_here"

# Windows PowerShell
$env:AIKB_BASE_URL="http://localhost:8080/api/v1"
$env:AIKB_API_KEY="your_api_key_here"

# Windows CMD
set AIKB_BASE_URL=http://localhost:8080/api/v1
set AIKB_API_KEY=your_api_key_here
```

Create the API key under Settings → Publish & Integrations → API Integration → API Keys.

| Variable | Default | Purpose |
| --- | --- | --- |
| `AIKB_BASE_URL` | `http://localhost:8080/api/v1` | AI KB API base URL |
| `AIKB_API_KEY` | empty | API key, sent as `X-API-Key` |
| `AIKB_CHAT_TIMEOUT` | `300` | Chat stream read timeout in seconds |
| `AIKB_VERIFY_SSL` | `true` | `false` disables TLS verification (development only) |
| `MCP_TRANSPORT` | `stdio` | `stdio`, `sse` or `http` (same as `--transport`) |
| `MCP_HOST` / `MCP_PORT` | `127.0.0.1` / `8000` | Bind address for `sse` and `http` |
| `MCP_SERVER_AUTH_TOKEN` | empty | Required for `sse` and `http`; the server refuses to start without it |
| `MCP_ALLOWED_UPLOAD_DIRS` | working directory | Extra roots for local file uploads (see below) |

### 3. Run the server

```bash
ai-kb-mcp-server                      # stdio, for MCP clients that launch the server
ai-kb-mcp-server --help               # show help
ai-kb-mcp-server --check-only         # check the environment configuration only
ai-kb-mcp-server --verbose            # enable verbose logging
ai-kb-mcp-server --version            # show the version
```

### Network transports

```bash
MCP_SERVER_AUTH_TOKEN=change_me ai-kb-mcp-server --transport http --host 0.0.0.0 --port 8000
```

The Streamable HTTP endpoint is `/mcp`; the SSE transport serves `/sse` and `/sse/messages/`.
Clients send `Authorization: Bearer <token>` or `X-MCP-Auth-Token: <token>`.

## Run from a source checkout

From the `mcp-server/` directory of the [repository](https://github.com/jrmatherly/ai-kb/tree/main/mcp-server):

```bash
pip install -r requirements.txt
python main.py                        # same options as ai-kb-mcp-server

# Or install the checkout
pip install .                         # pip install -e . for development
uvx --from . ai-kb-mcp-server         # without installing
```

`python run_server.py`, `python run.py`, `python aikb_mcp_server.py` and `python -m aikb_mcp_server` also start the server.

### Build distribution packages

```bash
pip install build
python -m build
```

### Test the module

```bash
python test_module.py
```

## Features

The MCP server provides these tools:

### Workspace management

- `create_tenant` - create a workspace
- `list_tenants` - list all workspaces

### Knowledge base management

- `create_knowledge_base` - create a knowledge base
- `list_knowledge_bases` - list knowledge bases
- `get_knowledge_base` - get knowledge base details
- `list_shared_knowledge_bases` - list knowledge bases shared with you
- `delete_knowledge_base` - delete a knowledge base
- `hybrid_search` - hybrid search

### Knowledge management

- `create_knowledge_from_file` - create knowledge from a local file
- `create_knowledge_from_url` - create knowledge from a URL
- `create_knowledge_from_text` - create knowledge from text
- `update_knowledge_from_text` - update manual Markdown knowledge, re-index it or save it as a draft
- `list_knowledge` - list knowledge
- `get_knowledge` - get knowledge details
- `delete_knowledge` - delete knowledge

### Model management

- `create_model` - create a model
- `list_models` - list models
- `get_model` - get model details

### Session management

- `create_session` - create a chat session
- `get_session` - get session details
- `list_sessions` - list sessions
- `delete_session` - delete a session

### Chat

- `chat` - send a chat message
- `agent_chat` - call an agent for multi-step retrieval and tool calls

Both chat tools assemble events on SSE blank-line boundaries, so one event can span several `data:` lines.
An event still open when the connection ends (no blank line seen yet) is dropped. Each event's data buffer is capped at 8 MiB;
exceeding the cap returns an error and closes the response connection.

### Agents

- `list_agents` - list agents
- `get_agent` - get agent details

### Chunk management

- `list_chunks` - list knowledge chunks
- `delete_chunk` - delete a knowledge chunk

### Wiki

- `wiki_search` - search a knowledge base's wiki pages
- `wiki_read_page` - read one wiki page by slug
- `wiki_index_view` - show a knowledge base's wiki index

## Troubleshooting

If you hit import errors, make sure that:

1. All required dependencies are installed
2. Your Python version is compatible (3.11 or newer)
3. No file name conflicts (do not name a file `mcp.py`)

### Local upload directory boundary

All transports, including stdio, restrict local file uploads to the working
directory by default. Set `MCP_ALLOWED_UPLOAD_DIRS` to a comma-separated list of
trusted absolute directories when additional roots are needed. Starting in a
filesystem root requires an explicit directory configuration. Paths and symbolic
links resolving outside the selected roots are rejected.
