# UniIndex

**Repository Path**: bytesifter/uni-index

## Basic Information

- **Project Name**: UniIndex
- **Description**: Unified Index
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-09
- **Last Updated**: 2026-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Uni-Index MCP 服务器

基于 PageIndex 的本地私有化文档索引服务，提供 MCP (Model Context Protocol) 接口 over SSE。

## 特性

- **MCP over SSE** — 基于 SSE 的模型上下文协议传输，支持会话管理、双向 ping
- **文档索引与搜索** — 关键词搜索、文档内容读取、目录结构提取
- **三种 MCP 能力** — Tools（搜索/状态）、Resources（文档 URI 读取）、Prompts（研究模式）
- **Bearer Token 认证** — 可配置的 API Key 认证
- **统一日志系统** — HTTP + MCP 日志，敏感信息自动脱敏
- **配置灵活** — YAML 配置文件 + 环境变量覆盖

## 快速启动

```bash
# 安装依赖
uv sync

# 启动服务器（默认 localhost:8000）
uv run uni-index

# 指定端口和日志级别
uv run uni-index --port 8000 --log-level DEBUG
```

**命令行参数：**
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--host` | `localhost` | 服务器绑定地址 |
| `--port` | `8000` | 监听端口 |
| `--log-level` | `INFO` | 日志级别 |

## 核心能力

| 能力 | 说明 | 详情 |
|------|------|------|
| `get_server_status` | 服务器状态信息 | 无参数 |
| `search_document` | 关键词搜索文档 | `query`(必填), `document_name`, `max_results` |
| `uni-index://documents/{name}` | 读取文档内容/结构/行范围 | 资源模板 |
| `research` | 多模式文档研究 | search/analyze/compare |

## 配置 OpenCode / Claude

```json
{
  "mcpServers": {
    "uni-index": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

启用认证时添加请求头：
```json
{
  "mcpServers": {
    "uni-index": {
      "url": "http://localhost:8000/mcp",
      "headers": { "Authorization": "Bearer your-api-key" }
    }
  }
}
```

## 文档导航

| 文档 | 说明 |
|------|------|
| [安装指南](docs/getting-started/installation.md) | 系统要求、安装步骤 |
| [快速上手](docs/getting-started/quick-start.md) | 5 分钟启动和测试 |
| [MCP 核心概念](docs/user-guide/concepts.md) | SSE、会话、工具/资源/提示 |
| [服务配置](docs/user-guide/configuration.md) | 配置项、环境变量 |
| [API 概览](docs/api-reference/overview.md) | JSON-RPC、会话生命周期 |
| [端点参考](docs/api-reference/endpoints.md) | 所有端点详情和示例 |
| [协议流程](docs/api-reference/protocol-flow.md) | 完整交互序列 |
| [架构文档](docs/developer-guide/architecture.md) | 组件结构和数据流 |

## 开发说明

项目遵循 OpenSpec 开发流程和团队编码规范，详见 `openspec/agents/`。

```bash
# 测试服务器
uv run uni-index --port 8001
```

## 许可证

Apache 2.0 — 详见 [LICENSE](LICENSE)