index-server

Index Server

通过 Model Context Protocol（MCP）为 AI Agent 提供受治理的知识库。

🚀 快速入门指南 — 5 分钟内完成配置并启动，支持 HTTPS 和语义搜索

📖 用例场景 — 面向支持工程师、开发团队和知识管理的真实示例

什么是 Index Server？

Index Server 是一个中心知识库，AI Agent 可通过 Model Context Protocol（MCP）连接到它。Agent 可以搜索、读取和贡献知识，这些知识会在不同会话和代码库之间持续保留，从而构建一个带有版本控制、审计跟踪和审批工作流的受治理目录。可选的管理仪表板可实时监控目录健康状况、使用情况分析和偏移检测。

前置条件：Node.js

使用 npx 或源码安装选项之前，Index Server 需要 Node.js 22 或更高版本。从 nodejs.org 下载 Node.js，或在管理员提示符下通过 Windows Package Manager 安装：

winget install OpenJS.NodeJS.LTS

快速入门选项

选项 A：通过 npx 原生使用 MCP（推荐）

无需克隆代码库即可运行最新发布的包。如果你希望快速在本地启动且已安装 Node.js，请选择此选项。

先运行设置向导，以便为 VS Code、Copilot CLI 或 Claude Desktop 生成正确的 MCP 客户端配置：

npx -y @jagilber-org/index-server@latest --setup

如需不使用向导而直接启动服务：

npx -y @jagilber-org/index-server@latest --dashboard

希望在 PATH 中使用稳定的 index-server 命令？ 请改为全局安装：npm install -g @jagilber-org/index-server，然后运行 index-server --setup / index-server --dashboard。GitHub Packages 镜像需要身份验证，因此使用 npx 访问 npm.pkg.github.com 时，需要配置每个作用域的 .npmrc，并提供具有 read:packages 权限的 GITHUB_TOKEN。

升级后出现“不支持的 INDEX_SERVER key”/“Cannot find module”错误？ 运行向导引导的清理：index-server --uninstall（别名：--remove、--clean）。你可以选择性地删除数据路径、MCP 客户端条目和全局包，也可以使用 --non-interactive --all 清除所有内容。完整说明请参阅升级和卸载。

为仪表板配置 HTTPS

使用一条命令生成自签名 TLS 证书和密钥：

# Generate at ~/.index-server/certs/, then start with HTTPS automatically
npx -y @jagilber-org/index-server@latest --init-cert --start --dashboard

单独使用 --init-cert 时，生成完成后即退出。使用 --init-cert --start 时，则会继续正常启动，并自动将生成的证书配置到 --dashboard-tls。

前置条件： openssl 必须位于 PATH 中。在 Windows 上，推荐将 Git for Windows （git.exe）作为 TLS 前置条件，因为它附带 openssl 构建版本，通常位于 C:\Program Files\Git\usr\bin\openssl.exe。如果缺少该程序，请在管理员提示符下安装 Git for Windows：

winget install --id Git.Git -e --source winget

有关配置说明、完整的标志参考、安全说明和故障排除，请参阅 docs/cert_init.md。

选项 B：VS Code MCP 配置

使用 VS Code 内置的 MCP 支持，配置 .vscode/mcp.json 或全局 mcp.json。你可以手动添加服务条目，也可以运行 npx -y @jagilber-org/index-server@latest --setup 自动生成配置。

选项 C：Docker

在容器中运行服务。如果你希望隔离运行时依赖，或正在准备基于容器的部署，请选择此选项。

docker compose up        # HTTP on :8787
docker compose up tls    # HTTPS on :8787 with self-signed certs

有关卷、环境变量和生产环境配置，请参阅 Docker 部署指南。

选项 D：从源代码构建

自行克隆并构建此存储库。如果你想修改服务、在本地运行测试，或使用最新源代码，请选择此选项。

git clone https://github.com/jagilber-org/index-server.git
cd index-server
npm install
npm run build

构建完成后，运行交互式设置向导，生成 .env 和 MCP 客户端配置：

node dist/server/index-server.js --setup
# or
npm run setup

配置 MCP 客户端

最佳实践： 将 INDEX_SERVER_DIR 设为常用数据文件夹，例如 C:/mcp/index-data/instructions 或 ~/.index-server/instructions。将其放在 VS Code 和 MCP 客户端配置路径之外，以免备份或重新安装时移动或覆盖你的目录。

{
  "servers": {
    "index-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@jagilber-org/index-server@latest",
        "--dashboard"
      ],
      "env": {
        "INDEX_SERVER_DIR": "C:/mcp/index-data/instructions",
        "INDEX_SERVER_LOG_LEVEL": "info"
      }
    }
  }
}

{
  "mcpServers": {
    "index-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jagilber-org/index-server@latest", "--dashboard"],
      "env": {
        "INDEX_SERVER_DIR": "C:/mcp/index-data/instructions",
        "INDEX_SERVER_LOG_LEVEL": "info"
      },
      "tools": ["*"]
    }
  }
}

{
  "mcpServers": {
    "index-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jagilber-org/index-server@latest", "--dashboard"],
      "env": {
        "INDEX_SERVER_DIR": "C:/mcp/index-data/instructions",
        "INDEX_SERVER_LOG_LEVEL": "info"
      },
      "tools": ["*"]
    }
  }
}

如需了解高级模式、环境变量和 TLS 设置，请参阅 MCP 配置指南。

验证

• 服务会显示在 MCP 客户端的服务列表中
• 运行 tools/list，查看 50 多个可用工具
• 运行 prompts/list，发现设置、配置和验证提示词
• 运行 resources/list，发现快速入门和配置指南
• 仪表板（如已启用）：http://localhost:8787

内置 MCP 提示词和资源

支持 MCP 提示词和资源的客户端可以使用内置的只读设置指南：

• 提示词：setup_index_server、configure_index_server、verify_index_server
• 资源：index://guides/quickstart、index://guides/client-config、index://guides/verification

这些界面有意设计为静态且只读。你可以用它们获取设置帮助、检查配置以及验证或排查问题，而不会更改服务状态。

启用语义搜索（可选）

在上述任一 MCP 配置中添加一个环境变量，即可启用基于嵌入的相似度搜索：

"env": {
  "INDEX_SERVER_SEMANTIC_ENABLED": "1"
}

首次搜索时会下载约 90 MB 的模型（仅一次）。此后，所有搜索都会自动使用语义模式，无需更改代码。如需了解 GPU 加速和离线选项，请参阅快速入门指南。

教会你的 Agent

复制粘贴以下说明，让你的 AI Agent 自动发现并使用共享知识库。

全局说明（~/.github/copilot-instructions.md）

## Index Server
- If index-server MCP tools are available, use them as a shared knowledge base for validated cross-repo patterns and standards.
- Search before creating: use `index_search` with 2-5 keywords, then `index_dispatch` with action="get" for details.
- After learning something reusable, add it with `index_add` or promote from a repo with `promote_from_repo`.
- Index entries are promoted snapshots — always prefer current repo files over index content.

按存储库设置的说明（.github/copilot-instructions.md）

## Index Server Integration
- Search order: repo files → .instructions/ → index-server → external docs
- **Search before add/promote**: Always search for existing guidance before creating new instructions. Use `index_search` with relevant keywords and inspect top results.
- To retrieve: `index_search` → `index_dispatch` with action="get" and the instruction ID
- To contribute: validate locally in `.instructions/` first, then promote with `promote_from_repo`
- To maintain: use `index_dispatch` with action="groom" to clean duplicates, `index_governanceUpdate` to deprecate stale content
- Current repo state always wins over promoted index snapshots

仪表板

可选的管理仪表板提供 Grafana 深色主题界面，用于监控和目录管理：

如需了解详情，请参阅 dashboard.md。REST 客户端脚本（scripts/index-server-client.ps1 和 scripts/index-server-client.sh）可供 CI 流水线和子 Agent 在不使用 MCP 的情况下执行完整的 CRUD 操作，详见 tools.md。

主要功能

• 符合 MCP 协议 — 通过 stdio 完整支持 JSON-RPC 2.0，并进行架构验证
• 50 多种工具，用于搜索、CRUD、治理、分析、消息传递和反馈
• 语义搜索 — 可选的基于嵌入的相似性搜索（HuggingFace 模型）
• 引导安全机制 — 在全新安装时，需经人工确认后才能执行变更
• 跨仓库知识推广 — 在本地验证，然后将已验证的模式推广到共享目录
• 治理工作流 — 所有权、版本控制、审批状态和确定性治理哈希
• 提交后生命周期钩子 — 可选的创建／更新／移除／变更自动化，支持超时、并发、阻止、脱敏和故障隔离
• REST 客户端脚本 — 为无需 MCP 的 CI／Agent 提供 PowerShell 和 Bash 脚本

文档

安全

Index Server 不会进行任何遥测调用，在正常运行期间也不会向外部服务发送数据。由运维人员配置的生命周期钩子可以显式调用本地或远程集成；默认情况下，这些钩子处于禁用状态。仪表板默认仅绑定到 localhost。所有变更都会记录在审计日志中；可通过 INDEX_SERVER_MUTATION=0 强制设为只读；全新安装时，在通过引导工作流获得人工确认前，写入操作会受到限制。可在启动时禁用可选子系统（例如，设置 INDEX_SERVER_MESSAGING_ENABLED=0，即可移除所有 messaging_* MCP 工具和仪表板的 Messaging 标签页）。

有关漏洞报告，请参阅 SECURITY.md；有关数据收集政策和可选出站连接，请参阅 PRIVACY.md；有关离线部署和验证，请参阅 网络隐私指南。

开发

npm install          # Install dependencies
npm run build        # Build TypeScript
npm run setup        # Interactive configuration wizard (generates .env + mcp.json)
npm test             # Run the fast default suite
npm run test:slow    # Run heavy integration/perf tests
npm run test:all     # Run the full Vitest suite
npm run typecheck    # Type checking
npm run lint         # Linting

完整的工作流、代码规范和测试要求，请参阅 CONTRIBUTING.md。

许可证

MIT License — 详情请参阅 LICENSE 文件。

使用 Model Context Protocol (MCP)、TypeScript、Node.js、Vitest 和 AJV 构建。