Metadata-Version: 2.4
Name: ai-kb-mcp
Version: 1.1.1
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](./MCP_CONFIG.md) instead of the steps below.

### 1. Install dependencies

```bash
pip install -r requirements.txt
```

### 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

**Recommended: the main entry point:**

```bash
python main.py
```

**Other ways to run it:**

```bash
# Original launch script
python run_server.py

# Quick launch script
python run.py

# Run the server module directly
python aikb_mcp_server.py

# Run as a Python module
python -m aikb_mcp_server
```

### 4. Command-line options

```bash
python main.py --help                 # show help
python main.py --check-only           # check the environment configuration only
python main.py --verbose              # enable verbose logging
python main.py --version              # show the version
python main.py --transport http --port 8000   # Streamable HTTP (needs MCP_SERVER_AUTH_TOKEN)
```

### 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>`.

## Install as a Python package

### From the checkout

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

> The distribution is named **`ai-kb-mcp`** (`setup.py`, `pyproject.toml`) and is not published on PyPI, so install it from this repository.
> The MCP packages on PyPI under the upstream project's name belong to that project and read its own variable names, not `AIKB_*`.
> The command-line entry points are `ai-kb-mcp-server` and `ai-kb-server`.

### Development install

```bash
pip install -e .
```

After installation you can use the command-line tools:

```bash
ai-kb-mcp-server
# or
ai-kb-server
```

### Production install

```bash
pip install .
```

### Build distribution packages

```bash
# With setuptools
python setup.py sdist bdist_wheel

# With modern build tooling
pip install build
python -m build
```

## Test the module

Run the test script to check that the module works:

```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.
