内容
# 资源分析、可视化和企业导航（RAVEN）
本地优先的AI分析套件，适用于BC政府自然资源部门。连接到Jira、Confluence和Bitbucket，位于SiteMinder SSO之后，可连接到任何LLM — 在本地运行，默认情况下个人信息被清除后才到达模型。
由Connected Services BC（自然资源部门数字服务）的Epsilon团队构建。
> **文档：** 安装和用法（此文件）· [工具目录和环境变量](docs/TOOL_INVENTORY.md) · [架构和安全](docs/SYSTEM_DESIGN_AND_ARCHITECTURE.md)
## 功能
RAVEN为本地LLM提供直接访问我们的Atlassian工具， 通过[MCP（模型上下文协议）](https://modelcontextprotocol.io/)服务器，并包括一个**自主DevOps流水线**，该流水线可以检测生产错误，使用AI进行分类，生成代码修复，并创建拉取请求。
| 服务器 | 功能 |
|--------|-----------------|
| **Jira** | 通过JQL搜索；读取/创建/更新/评论/转换问题（Epic Link感知）；记录时间；管理观察者，版本和冲刺生命周期；链接问题 |
| **Confluence** | 搜索（CQL + 过滤）；导航空间树；以Markdown读取/创建/更新/删除/移动页面；管理附件，标签和评论 |
| **Bitbucket** | 浏览/搜索代码；审查PR（差异，评论，批准，合并，拒绝）；提交历史和责备；标签；CI构建状态；创建分支和PR |
| **Azure DevOps** | 工作项（WIQL），仓库和分支，拉取请求和构建管道，在本地Azure DevOps服务器上 |
| **资产（CMDB）** | 查询Jira资产CMDB — 应用程序，环境，技术栈，人，组织投资组合；对象/模式自省 |
| **服务器监视器** | 发现已部署的应用程序；搜索Tomcat/Apache日志；比较版本；差异配置；JVM堆（只读，通过SSH） |
| **IMIS** | 搜索服务器库存并SSH浏览应用程序和配置（只读） |
| **Sonar** | 代码问题，质量门，安全热点，项目指标和本地`sonar-scanner`运行 |
| **Artifactory** | 仓库，工件，校验和，属性，AQL搜索，构建信息，保护传输和防护复制/移动/删除操作 |
| **Jenkins** | 检查和配置作业；运行和监视构建；管理队列项，工件，推广和凭证元数据/生命周期 |
| **RFC Buddy** | 从当前/已完成的计划中过滤和搜索RFC；更新/推进API侧基准线 |
| **健康** | 冲刺速度，问题老化，综合健康得分，工作量，投资组合比较 |
| **概览** | 一次性跨系统项目摘要（Jira + Confluence + Bitbucket） |
| **错误分类器** | 按共享根原因聚类Jira错误 |
| **Jarvis** | 查询中央Jarvis应用程序库存（动态代理到BC Gov API） |
参见 **[`docs/TOOL_INVENTORY.md`](docs/TOOL_INVENTORY.md)** 获取完整的工具目录，每个服务器的计数和读写分割。Atlassian支持的服务器（Jira，Confluence，Bitbucket，资产，概览，健康，错误分类器）共享一个单一的身份验证会话 — 登录一次，到处使用。服务器监视器，IMIS，Azure DevOps，Jarvis，Sonar，Jenkins，Artifactory和RFC Buddy分别通过`~/.raven/.env`中的凭证进行身份验证。
### 自主流水线（`@nrs/pipeline`）
一个独立的CLI，通过SSH检测生产错误，使用AI进行分类，生成代码修复并创建拉取请求 — 所有操作都是自主的。使用GitHub Copilot SDK与`claude-sonnet-4.6`。支持单次运行，监视模式和Jira积压模式。
参见 [AUTONOMOUS_DEVOPS_PIPELINE.md](AUTONOMOUS_DEVOPS_PIPELINE.md) 获取架构，参见 [DEVOPS_PIPELINE_USAGE.md](DEVOPS_PIPELINE_USAGE.md) 获取CLI用法。
### 服务器监视器Web UI（`@nrs/server-ui`）
一个用于监视BC Gov应用程序服务器的Web仪表板 — 错误计数，日志搜索，JVM堆，已部署版本，配置差异，部署历史和警报。在`http://localhost:3777`本地运行。
参见 [SERVER_MONITOR_UI.md](SERVER_MONITOR_UI.md) 获取安装和用法。
### 搜索排名
Jira搜索结果通过相关性（0-100）进行评分和排名：
- **时间** （35%）— 最近更新的问题排名更高
- **状态** （25%）— 进行中/打开状态高于完成/关闭状态
- **内容丰富度** （20%）— 描述良好的问题带有标签/组件得分更高
- **搜索排名** （10%）— Jira自己的相关性排序
- **优先级** （10%）— 阻碍/关键问题高于低优先级问题
结果按年龄段分组：当前（<1年），最近（1-3年），旧版（>3年）。
### Confluence排名
Confluence搜索结果通过相关性（0-100）进行评分和排名：
- **时间** （40%）— 最近更新的页面排名更高（页面比问题更快过期）
- **搜索排名** （30%）— Confluence自己的CQL相关性排序
- **内容信号** （20%）— 摘录存在和长度作为页面丰富度的代理
- **标题匹配** （10%）— 查询词出现在页面标题时的奖励
结果按年龄段分组：当前（<1年），最近（1-3年），过期（>3年）。搜索工具指示LLM始终通过`read_pages`读取顶部页面，然后再总结 — 而不是简单地列出搜索结果。
## 先决条件
- **Node.js** >= 20 （检查：`node -v`）
- **Playwright** 浏览器（在第一次构建时自动安装）
- **支持MCP的聊天客户端** — 参见 [选择客户端](#choosing-a-client)
- **BC Gov IDIR凭证** 用于SiteMinder身份验证
## 快速入门
### 1. 克隆和构建
RAVEN是一个TypeScript monorepo（npm工作区）：
```bash
git clone https://github.com/bcgov/raven.git ~/Projects/raven
cd ~/Projects/raven
npm install
npm run build
```
### 2. 配置身份验证
复制环境模板并填写您的凭证：
```bash
mkdir -p ~/.raven && chmod 700 ~/.raven
cp .env.example ~/.raven/.env
chmod 600 ~/.raven/.env
```
然后编辑`~/.raven/.env`并填写您的值：
```env
ATLASSIAN_BASE_URL=<基准网址，包括https>
ATLASSIAN_EMAIL=<您的gov.bc.ca邮箱>
ATLASSIAN_PASSWORD=<您的IDIR密码>
RAVEN_SCRUB_PI=true
```
可选的Jira设置，用于编写Epic链接：
```env
# Jira Epic链接自定义字段ID（默认值：customfield_10006）
JIRA_EPIC_LINK_FIELD=customfield_10006
```
可选的Azure DevOps设置：
```env
# Azure DevOps服务器（本地）
ADO_BASE_URL=<https://your-ado-server.example.com>
ADO_DEFAULT_COLLECTION=<默认集合，例如DefaultCollection>
ADO_PAT=<您的个人访问令牌>
ADO_DEFAULT_PROJECT=<默认团队项目名称>
# ADO_API_VERSION=7.1
```
可选的Jarvis API设置：
```env
# Jarvis应用程序库存令牌和自定义网址（默认为Jarvis端点）
JARVIS_TOKEN=<您的Jarvis授权令牌>
# JARVIS_BASE_URL=https://jarvis-api.example.gov.bc.ca/mcp
```
可选的SonarQube设置：
```env
# SonarQube基准网址和身份验证凭证
SONARQUBE_URL=<SonarQube基准网址，例如https://sonarqube.example.gov.bc.ca/sonar>
SONARQUBE_TOKEN=<您的SonarQube用户令牌>
SONAR_SCANNER_BIN=<可选的sonar-scanner二进制文件路径，如果不在PATH中>
```
可选的Jenkins设置：
```env
JENKINS_URL=<您的HTTPS Jenkins基准网址>
# 专用基本身份验证优先用于自主操作：
# JENKINS_USER=<您的Jenkins用户名>
# JENKINS_TOKEN=<您的Jenkins API令牌>
# 可选的保护目录：
# RAVEN_JENKINS_CONFIG_DIR=~/.raven/jenkins-configs
# RAVEN_JENKINS_DOWNLOAD_DIR=~/.raven/jenkins-downloads
# RAVEN_JENKINS_SECRET_DIR=~/.raven/jenkins-secrets
```
如果未设置专用的Jenkins凭证，Jenkins MCP将回退到缓存的SMSESSION身份验证。作业配置更新需要预期的SHA-256和确切的XML来自保护的配置文件。凭证写入接受环境变量或模式限制的文件中的机密引用；不接受原始机密值作为工具参数。
可选的RFC Buddy设置：
```env
# RFC Buddy基准网址和个人访问令牌
RFCBUDDY_URL=<RFC Buddy API基准网址，例如https://rfcbuddy.example.com/api/v1>
RFCBUDDY_PAT=<您的个人访问令牌（PAT）>
```
可选的Artifactory设置：
```env
# HTTPS是强制性的。这些专用变量故意不回退到
# ATLASSIAN_*，即使两个服务目前使用相同的IDIR帐户。
ARTIFACTORY_URL=<内部Artifactory HTTPS基准网址；询问RAVEN维护者>
ARTIFACTORY_EMAIL=<您的gov.bc.ca邮箱>
ARTIFACTORY_PASSWORD=<您的IDIR密码>
# RAVEN_ARTIFACTORY_UPLOAD_DIR=~/.raven/artifactory-uploads
# RAVEN_ARTIFACTORY_DOWNLOAD_DIR=~/.raven/artifactory-downloads
# RAVEN_ARTIFACTORY_MAX_TRANSFER_BYTES=536870912
# RAVEN_ARTIFACTORY_DOWNLOAD_TIMEOUT_MS=1800000
# RAVEN_ARTIFACTORY_DOWNLOAD_REDIRECT_HOSTS=<逗号分隔的批准存储主机名>
```
创建传输目录时仅需执行此操作，并使用`chmod 700`限制访问权限；上传源文件必须是具有`600`模式的常规文件。Artifactory凭证仅在本地MCP进程中附加到请求中，并仅发送到配置的HTTPS端点。
使用Jira MCP工具时，`create_issue`和`update_issue`都接受一个可选的`epicKey`参数来设置Epic链接。
> **我在哪里获得ATLASSIAN_BASE_URL？** 这是一个内部BWA（基本Web身份验证）主机名，它绕过SiteMinder。不公开发布。向RAVEN维护者或团队负责人询问网址。
每个MCP服务器在启动时通过`dotenv`加载此文件 — 凭证永远不会出现在MCP客户端配置中或暴露给LLM。有关详细信息，请参见 [身份验证](#authentication)。
### 3. 连接到您的LLM客户端
将此MCP配置复制到您的客户端（参见 [选择客户端](#choosing-a-client) 以了解粘贴位置）：
```json
{
"mcpServers": {
"jira": {
"command": "node",
"args": ["/path/to/raven/packages/jira-mcp/dist/index.js"]
},
"confluence": {
"command": "node",
"args": ["/path/to/raven/packages/confluence-mcp/dist/index.js"]
},
"bitbucket": {
"command": "node",
"args": ["/path/to/raven/packages/bitbucket-mcp/dist/index.js"]
},
"overview": {
"command": "node",
"args": ["/path/to/raven/packages/overview-mcp/dist/index.js"]
},
"health": {
"command": "node",
"args": ["/path/to/raven/packages/health-mcp/dist/index.js"]
},
"server-monitor": {
"command": "node",
"args": ["/path/to/raven/packages/server-mcp/dist/index.js"]
},
"imis": {
"command": "node",
"args": ["/path/to/raven/packages/imis-mcp/dist/index.js"]
},
"assets": {
"command": "node",
"args": ["/path/to/raven/packages/assets-mcp/dist/index.js"]
},
"bug-classifier": {
"command": "node",
"args": ["/path/to/raven/packages/bug-classifier-mcp/dist/index.js"]
},
"ado": {
"command": "node",
"args": ["/path/to/raven/packages/ado-mcp/dist/index.js"]
},
"jarvis": {
"command": "node",
"args": ["/path/to/raven/packages/jarvis-mcp/dist/index.js"]
},
"sonar": {
"command": "node",
"args": ["/path/to/raven/packages/sonar-mcp/dist/index.js"]
},
"jenkins": {
"command": "node",
"args": ["/path/to/raven/packages/jenkins-mcp/dist/index.js"]
},
"rfcbuddy": {
"command": "node",
"args": ["/path/to/raven/packages/rfcbuddy-mcp/dist/index.js"]
},
"artifactory": {
"command": "node",
"args": ["/path/to/raven/packages/artifactory-mcp/dist/index.js"]
}
}
}
```
**重要：** 将`/path/to/raven`替换为您的实际克隆路径（例如`~/Projects/raven`）。凭证和设置（包括PI擦除）从`~/.raven/.env`加载 - 它们不属于此配置文件。
### 4. 配置服务器监控（可选）
服务器监控MCP需要两件事：一个`servers.conf`文件列出它可以连接的服务器，以及`~/.raven/.env`中的SSH凭证。
#### 4a. 创建`~/bin/servers.conf`
此文件是服务器名称和连接详情的单一真实来源。如果缺少或为空，服务器监控MCP将**失败启动**。
```bash
cp servers.conf.example ~/bin/servers.conf
```
然后编辑`~/bin/servers.conf`并用您自己的值替换示例主机名和`_A`帐户。格式是用管道分隔的：```
name|hostname|ssh_user|sudo_user|role|description
```
参见存储库根目录中的[`servers.conf.example`](servers.conf.example)获取完整的格式参考，包括可选的`apps_base`和`logs_base`字段。
> **自定义位置：** 如果您希望将`servers.conf`放在`~/bin/`以外的其他位置，请在`~/.raven/.env`中设置`SERVER_TOOLS_BIN=/path/to/dir`。
#### 4b. 将SSH凭证添加到`~/.raven/.env`
```env
SERVER_A_PASSWORD=<您的_A帐户密码>
```
**注意：** 引号如果包含`#`或其他特殊字符，请引用密码。服务器监控器需要VPN连接到BC Gov网络。
`ssh_user`（您的`_A`帐户）直接从`servers.conf`读取 - 您不需要单独在`.env`中设置它。
#### 4c. 可选：SSH密钥身份验证（每主机选择）
默认情况下，服务器监控器和IMIS使用`SERVER_A_PASSWORD`进行密码身份验证。如果您已将公钥部署到一个或多个目标服务器，您可以通过设置**两者来选择基于密钥的SSH身份验证：
```env
SSH_KEY_PATH=/Users/<you>/.ssh/id_ed25519
SSH_KEY_HOSTS=int01,test01,prod01
```
工作原理：
- 对于列出的主机，请使用密钥身份验证 - 没有提供ssh2，因此拒绝的密钥（例如密钥从服务器删除）会大声失败而没有回退的密码尝试。
- **不**列出的主机，请使用密码身份验证 - 不提供密钥，因此不会生成失败的publickey日志条目。
- 这会产生零个失败登录尝试的稳定状态，对任何主机而言。（参见“为什么每主机”下面）
要求：
- `SERVER_A_PASSWORD`需要密码身份验证（任何主机不设置密钥身份验证）并且在远程服务器上使用sudo。大多数服务器监控器工作流使用sudo进行服务帐户访问，因此请计划保持设置，除非您对每个主机都使用密钥身份验证并且永远不会sudo。
- 密钥文件必须存在于指定的路径。如果`SSH_KEY_PATH`设置但文件缺失，Raven会返回明确的错误而不是尝试任何连接。
- 设置`SSH_KEY_PATH`而设置`SSH_KEY_HOSTS`被拒绝并报错 - 将是模糊的身份验证方式。
`SSH_KEY_HOSTS`匹配：
- 逗号分隔的短名称（例如`int01`的示例不适用于`int01`，而是`int01`）。 Raven规范化传入的主机名，将其小写并剥离域名，然后再进行匹配，因此像`int01.example.internal`这样的FQDN与列表条目`int01`匹配。
- 空格周围的条目将被修剪。`int01, test01`有效。
- 使用`SSH_KEY_HOSTS=*`将密钥用于每个主机（严格 - 如果`authorized_keys`中没有密钥，则会硬性失败）。
行为：
- 如果`SSH_KEY_PATH`已设置但文件丢失，Raven会返回明确的错误，而不是尝试任何连接。
- 设置`SSH_KEY_PATH`而不设置`SSH_KEY_HOSTS`被拒绝并报错 - 这将不明确是否应在给定主机上使用密钥。
- 如果您的私钥具有通行短语，也请设置`SSH_KEY_PASSPHRASE`：
```env
SSH_KEY_PASSPHRASE=<私钥的通行短语>
```
`SSH_KEY_HOSTS`匹配：
- 逗号分隔的短名称（例如`int01`，而不是`int01.example.internal`）。 Raven规范化传入的主机名，将其小写并剥离域名，然后进行匹配，因此FQDN（如`int01.example.internal`）与列表条目`int01`匹配。
- 条目周围的空格将被修剪。`int01, test01`有效。
- 使用`SSH_KEY_HOSTS=*`将密钥用于每个主机（严格 - 如果`authorized_keys`中没有密钥，则会硬性失败）。
为什么按主机（而不是“尝试密钥，退后尝试密码”）：尝试-然后-回退的方法会在每个服务器上生成一个失败的公钥登录条目。乘以每天的调用次数，这个数字会很多，表现为堡垒警报（fail2ban，MaxAuthTries）。按主机设计完全消除了这一点 - 成本是维护新服务器上的密钥列表。
### 5. 配置IMIS服务器库存（可选）
IMIS MCP服务器从IMIS服务器数据库的本地CSV导出读取。该文件包含敏感的基础设施数据，**不包含在仓库中** - 您必须自己导出。
1. 将IMIS客户端的CSV导出为CSV
2. 将其放在`~/.raven/imis-servers.csv`
```bash
# 或通过环境变量在~/.raven/.env中设置自定义路径：
IMIS_CSV_PATH=/path/to/your/imis-export.csv
```
三个发现工具（`search_servers`，`get_server`，`server_stats`）从此CSV本地读取 - 无需网络。三个SSH工具（`list_server_apps`，`explore_server`，`read_server_file`）直接连接到服务器，需要VPN访问和`SERVER_A_PASSWORD`在`~/.raven/.env`中。
### 6. 验证它是否有效
测试单个服务器以确认身份验证正常：
```bash
# 快速烟雾测试 - 应该打印服务器信息而无错误
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node packages/jira-mcp/dist/index.js
```
如果您看到一个JSON响应，列出了可用的工具，那么就没问题了。如果您收到401错误，请再次检查`ATLASSIAN_BASE_URL`、`ATLASSIAN_EMAIL`和`ATLASSIAN_PASSWORD`在`~/.raven/.env`中。
然后在您的LLM客户端中尝试一个真正的查询：
> 在项目DEMO中搜索5个最近更新的票
如果结果返回，RAVEN就正常工作。
### 7. 提问
```
在项目PROJ1中搜索所有打开的票
查找关于DMS架构的Confluence页面
列出CWM Bitbucket项目中的仓库
给我一个项目DEMO的概览
分析项目PROJ1的冲刺速度
PROJ1项目的健康评分是多少？
比较项目DEMO、PROJ2和PROJ1的投资组合健康状况
检查int01上RRS rrs-api的堆
prod01上部署了哪些应用程序？
在RRS rrs-api上搜索prod上的ORA错误
比较所有环境中RRS rrs-api的context.xml
在IMIS中搜索所有PROD区域中的Windows服务器
RRS使用什么技术栈？
查找使用Oracle 19c的所有应用程序
CWM应用程序关联的人员是谁？
```
## 选择客户端
RAVEN 与任何支持 MCP 的客户端配合使用。以下是我们测试过的客户端：
| 客户端 | MCP 工具限制 | 本地模型 | 设置 |
|--------|----------------|--------------|-------|
| **VS Code + GitHub Copilot** | 无限制 | 否（使用 Copilot 模型） | 通过存储库根目录中的 `.mcp.json` 自动检测 |
| **LM Studio** | 无限制 | 是（内置模型运行器） | 右侧边栏 > 程序 > 编辑 mcp.json |
| **Dive** | 无限制 | 是（连接到 Ollama） | 设置 > MCP 配置 |
| **MstyStudio** | 1 个工具（免费）/ 无限制（付费） | 是（连接到 Ollama） | 工具箱 > 添加新工具 > 从 JSON 导入 |
### 带有 GitHub Copilot 的 VS Code（推荐）
RAVEN 在存储库根目录中包含一个 `.mcp.json` 文件，VS Code 会自动检测它。您需要一个 GitHub Copilot 许可证 - 如果您的组织尚未启用它，请参阅 [GitHub Copilot 设置指南](https://docs.github.com/en/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-organization)。
1. 在 VS Code 中打开 RAVEN 项目文件夹
2. 安装 [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) 和 [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) 扩展程序（如果尚未安装）
3. 打开 Copilot Chat（**⌃⌘I** on macOS，**Ctrl+Shift+I** on Windows/Linux）并切换到 **Agent** 模式
4. 您应该看到 RAVEN MCP 服务器列为可用工具
5. 如果提示“启动”或批准 MCP 服务器，请单击允许
**验证 MCP 服务器已连接：**
- 打开命令面板（**⌘⇧P** / **Ctrl+Shift+P**）并运行 **MCP: List Servers**
- 所有 12 个服务器都应显示为已注册 - 点击任意一个以启动/重启它
- 在 Copilot Chat 输入栏中，点击 **tools icon** （🔧）以查看可用工具
无需手动 MCP 配置 - 项目根目录中的 `.mcp.json` 处理所有事情。如果您需要自定义服务器路径，请直接编辑 `.mcp.json`。
#### 从任何项目使用 RAVEN（全局 VS Code 配置）
`.mcp.json` 方法仅在打开 RAVEN 文件夹时激活。要使所有 RAVEN 工具在 **每个** VS Code 工作区中可用，请将它们添加到您的 VS Code 用户级 MCP 配置中。
在以下位置创建或编辑文件：
- **macOS:** `~/Library/Application Support/Code/User/mcp.json`
- **Windows:** `%APPDATA%\Code\User\mcp.json`
- **Linux:** `~/.config/Code/User/mcp.json`
```json
{
"servers": {
"jira": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/jira-mcp/dist/index.js"]
},
"confluence": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/confluence-mcp/dist/index.js"]
},
"bitbucket": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/bitbucket-mcp/dist/index.js"]
},
"overview": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/overview-mcp/dist/index.js"]
},
"health": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/health-mcp/dist/index.js"]
},
"server-monitor": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/server-mcp/dist/index.js"]
},
"imis": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/imis-mcp/dist/index.js"]
},
"assets": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/assets-mcp/dist/index.js"]
},
"bug-classifier": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/bug-classifier-mcp/dist/index.js"]
},
"ado": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/ado-mcp/dist/index.js"]
},
"jarvis": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/jarvis-mcp/dist/index.js"]
},
"sonar": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/sonar-mcp/dist/index.js"]
},
"jenkins": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/jenkins-mcp/dist/index.js"]
},
"rfcbuddy": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/rfcbuddy-mcp/dist/index.js"]
},
"artifactory": {
"type": "stdio",
"command": "node",
"args": ["/path/to/raven/packages/artifactory-mcp/dist/index.js"]
}
}
}
```
将 `/path/to/raven` 替换为您的实际克隆路径（例如 `/Users/jsmith/Projects/raven`）。使用绝对路径 - 用户级配置不支持 `~` 扩展。
> **注意：** 用户级格式使用 `"servers"` 并要求每个条目为 `"type": "stdio"`。如果同时存在这两个文件，VS Code 会合并它们 - 工作区条目优先于具有相同名称的用户条目。
### LM Studio
1. 下载具有工具调用支持的模型（参见 [推荐模型](#推荐模型)）
2. 右侧边栏 > **程序** 选项卡 > **编辑 mcp.json**
3. 粘贴上面的 MCP 配置
4. 启动聊天并提问
### MstyStudio
1. 工具箱 > 添加新工具 > **从 JSON 剪贴板导入工具**
2. 单独粘贴每个服务器配置（仅限内部 JSON 对象）
3. 使用已启用的 RAVEN 工具创建 **工具集**
4. 使用工具集在插件中创建 **角色**
5. 选择支持工具调用的模型
6. 启动新聊天，选择您的角色并使用 **@** 图标
## 推荐模型
并非所有本地模型都支持工具调用。以下模型与 RAVEN 配合良好：
| 模型 | 大小 | 速度 | 工具调用 | 最适合 |
|-------|------|-------|-------------|----------|
| **Qwen3 Coder 30B** （Q4_K_M）| ~18GB | 中等 | 优秀 | 深度分析、代码审查、合成 |
| **Qwen 2.5 14B** （Q4_K_M）| ~8GB | 中等 | 优秀 | 深度分析、合成 |
| Qwen 2.5 7B | ~4GB | 快速 | 良好 | 例行搜索、快速查找 |
| Llama 3.1 8B | ~5GB | 快速 | 良好 | 一般任务 |
| Mistral Nemo 12B | ~7GB | 中等 | 良好 | 平衡速度/质量 |
### Ollama 性能调优
如果使用 Ollama 作为模型运行器，请在 `~/.zprofile` 中添加以下内容以提高速度：
```bash
# Flash Attention - 更快的推理，零质量损失
export OLLAMA_FLASH_ATTENTION=1
export OLLAMA_KV_CACHE_TYPE=q8_0
launchctl setenv OLLAMA_FLASH_ATTENTION 1
launchctl setenv OLLAMA_KV_CACHE_TYPE q8_0
```
在设置完成后重启 Ollama。
## 身份验证
RAVEN 支持两种身份验证方法。推荐使用基本身份验证。
### 基本身份验证（推荐）
通过内部 URL 使用 HTTP 基本身份验证绕过 SiteMinder。无需浏览器，无会话过期，无 Playwright 依赖。
在 `~/.raven/.env` 中创建具有以下三个变量的文件：
| 变量 | 描述 | 示例 |
|----------|-------------|---------|
| `ATLASSIAN_BASE_URL` | BWA 主机名（询问 RAVEN 维护者或团队负责人） | `https://...` |
| `ATLASSIAN_EMAIL` | IDIR 电子邮件地址 | `Your.Name@gov.bc.ca` |
| `ATLASSIAN_PASSWORD` | IDIR 密码 | （保持秘密） |
| `RAVEN_SCRUB_PI` | 在 LLM 之前匿名化名称 | `true` |
每个 MCP 服务器在启动时通过 `dotenv` 加载此文件。凭据仅注入服务器进程中 - 它们永远不会暴露给 LLM 客户端。
**安全：** 永远不要将凭据提交到 git。 `~/.raven/` 目录应为 `chmod 700`，`.env` 文件应为 `chmod 600`。密码保留在本地机器上 - RAVEN 永远不会登录或传输它。
### SMSESSION Cookie（备用）
如果未设置基本身份验证环境变量，RAVEN 将退后使用 SiteMinder Cookie 身份验证：
1. 检查缓存的会话（`~/.workflow-suite/session.json`）
2. 如果过期或丢失，请检查 `SMSESSION` 环境变量
3. 如果两者都不存在，则打开 Chromium 浏览器进行交互式 IDIR 登录
4. Cookie 缓存 25 分钟，在 Jira/Confluence/Bitbucket 中共享
```bash
# 通过浏览器身份验证
node packages/auth/dist/cli.js
```
## Jira 搜索示例（JQL）
`search_issues` 工具接受 [JQL（Jira 查询语言）](https://support.atlassian.com/jira-software-cloud/docs/use-advanced-search-with-jql/)：
```
-- 项目中的所有票证（最新）
project = PROJ1 ORDER BY updated DESC
-- 跨摘要和描述的文本搜索
text ~ "NROS Portal Retirement"
-- 仅打开的票证
project = DEMO AND status != Done ORDER BY updated DESC
-- 按分配人
assignee = currentUser() AND status = "In Progress"
-- 跨项目搜索应用
text ~ "RRS" AND project IN (PROJ1, PROJ2, DEMO) ORDER BY created DESC
-- 日期范围内的最近票证
project = PROJ1 AND created >= 2025-01-01 ORDER BY created DESC
-- 按标签
labels = "NROS_Portal_Retirement"
```
## 按角色划分的常见查询
将这些提示复制到您的 LLM 聊天中。它们与 RAVEN 的数据工具和健康分析工具配合使用。
### 产品负责人
**Sprint 健康检查：**
> 分析 PROJ1 在过去 5 个 Sprint 中的 Sprint 速度。我们的完成率正在改善还是下降？
**功能进度：**
> 在 Jira 中搜索所有带有标签 "Q4-Release" 的 DEMO 票证 - 完成和未完成的数量是多少？
**待办事项卫生：**
> 分析 DEMO 的问题老化。是否有超过 90 天的票证卡在待办事项中，我们应该整理或关闭？
**当前 Sprint 状态：**
> 为 DEMO 提供项目概述，然后告诉我哪些 Sprint 项目有风险无法完成。
**未分配的工作：**
> 分析 DEMO 的工作量。多少票证未分配，优先级是什么？
### 项目经理
**风险识别：**
> 分析 DEMO 的项目健康状况。我应该在下一次状态会议中提出哪些风险信号？
**资源冲突：**
> 分析 DEMO 和 PROJ2 之间的工作量。有人在两个项目之间过度负载吗？
**里程碑跟踪：**
> 在 Jira 中搜索 DEMO 里程碑为 "2.0-Release" 的票证 - 完成百分比是多少？
**停滞工作：**
> 分析 DEMO 的问题老化。哪些正在进行中的票证已超过 14 天未更新？
**跨项目可见性：**
> 获取 DEMO、PROJ2 和 PROJ1 的投资组合健康状况。哪个项目本周需要最多关注？
### 执行官/总监
**投资组合健康状况：**
> 对 DEMO、DMS、PROJ1 和 RRS 运行投资组合健康分析。给我一个页面总结当前状况。
**停滞项目检测：**
> 分析 DMS 的项目健康状况。过去 30 天内，是否有任何代码或文档活动？
**文档缺口：**
> 在 Confluence 中搜索有关 DEMO 的页面 - 架构和入职文档是最新的还是过时的？
**团队容量：**
> 分析 DEMO、PROJ2 和 PROJ1 的工作量。是否有人跨多个项目分配？
**交付趋势：**
> 分析 DEMO 在过去 10 个 Sprint 中的 Sprint 速度。团队的交付量是否增加或减少？
### 开发人员 / DevOps
**晨间检查：**
> 运行 RRS 的服务器仪表板。今天有任何错误吗？
**内存压力：**
> 检查生产环境 prod01 上 RRS rrs-api 的 JVM 堆栈。Old Gen 是否高于 80%？
**版本对齐：**
> 显示 RRS 在所有环境中的部署版本。开发环境和生产环境是否同步？
**配置漂移：**
> 比较所有环境中 RRS rrs-api 的 context.xml。开发环境和生产环境之间有差异吗？
**日志调查：**
> 在 prod01 上搜索 RRS rrs-api 的 ORA- 错误并带有 3 行上下文
**发现：**
> int01 上部署了哪些应用？列出所有组件和版本。
## 项目结构
RAVEN 是一个 TypeScript monorepo（npm 工作区）：
```
raven/ ← RAVEN 根目录（在此运行 npm 命令）
packages/
auth/ 共享身份验证（基本身份验证 + SiteMinder Cookie 缓存）
jira-mcp/ Jira 数据中心 MCP 服务器（搜索、问题、sprint、版本、观察者、工作日志、附件、用户）
confluence-mcp/ Confluence 数据中心 MCP 服务器（搜索/CQL、页面、层次结构、附件、标签、评论）
bitbucket-mcp/ Bitbucket 数据中心 MCP 服务器（代码搜索、PR 审查、提交、责备、标签、构建状态）
overview-mcp/ 跨系统项目概述 MCP 服务器
health-mcp/ 项目健康分析 MCP 服务器
server-mcp/ 服务器监控 MCP 服务器（SSH）
imis-mcp/ IMIS 服务器库存 MCP 服务器（CSV + SSH）
assets-mcp/ Jira 资产 CMDB MCP 服务器（搜索、对象、历史记录、模式）
bug-classifier-mcp/ Bug 模式分类器 MCP 服务器
ado-mcp/ Azure DevOps 服务器 MCP（工作项、仓库、PR、管道）
jarvis-mcp/ Jarvis 代理 MCP 服务器（动态远程代理到 Jarvis 应用程序库存）
sonar-mcp/ SonarQube MCP 服务器（问题、质量门、热点、指标、本地扫描）
jenkins-mcp/ Jenkins MCP 服务器（作业、构建、队列、工件、促销、凭证）
rfcbuddy-mcp/ RFC 朋友 MCP 服务器（RFC 日程搜索和基线跟踪）
artifactory-mcp/ JFrog Artifactory MCP 服务器（工件、构建信息、受控传输）
pipeline/ 自主 DevOps 流水线 CLI（GitHub Copilot SDK + MCP 工具）
raven-cli/ CLI 接口（即将推出）
server-ui/ 服务器监控 Web UI（参见 SERVER_MONITOR_UI.md）
.mcp.json Claude Code 自动配置（相对路径）
tsconfig.json TypeScript 项目引用
SERVER_MONITOR_UI.md 服务器监控 Web UI 设置和使用
AUTONOMOUS_DEVOPS_PIPELINE.md 流水线架构与设计
DEVOPS_PIPELINE_USAGE.md 流水线 CLI 参考示例
```
## 开发
所有命令均从存储库根目录运行：
```bash
cd ~/Projects/raven # 或您克隆 raven 的位置
# 构建所有软件包
npm run build
# 运行测试
npm test
# 监视模式
npm run test:watch
# 清洁构建工件
npm run clean
```
## 隐私与合规
- **所有数据都保留本地。** 没有 Atlassian 数据发送到外部 LLM 提供商。
- **符合 FOIPPA。** 来自 Jira/Confluence 的个人信息仅在本地处理。
- **PI 擦拭。** 设置 `RAVEN_SCRUB_PI=true` 在 `~/.raven/.env` 中，以便在 LLM 到达之前自动匿名化个人信息（姓名、用户名）。一个设置控制所有服务器。
- **您的 IDIR 凭证。** RAVEN 以您的身份进行身份验证 - 它看到的与您看到的完全相同，没有更多。
- **代码中没有机密。** 凭证在服务器启动时从 `~/.raven/.env` 加载 - 永远不会通过 MCP 客户端配置传递，从不暴露给 LLM，从不记录或存储在存储库中。
## 故障排除
### 身份验证错误（401 或“未找到有效的 SMSESSION”）
检查 `~/.raven/.env` 是否具有正确的 `ATLASSIAN_BASE_URL`、`ATLASSIAN_EMAIL` 和 `ATLASSIAN_PASSWORD` 值。确保 URL 包含 `https://`。或者运行 `node packages/auth/dist/cli.js` 以备 SMSESSION（在 25 分钟后过期）。
### 模型描述工具而不是调用它们
您的 LLM 不支持工具调用。切换到 **Qwen 2.5 14B** 或 **Llama 3.1 8B**。参见 [推荐模型](#推荐模型)。
### 服务器监控 MCP 启动失败（“未配置服务器”）
`server-mcp` 读取 `~/bin/servers.conf` 并在找不到任何条目时拒绝启动。使用 [配置服务器监控](#4-配置服务器监控（可选）中描述的格式创建文件。如果您的文件位于其他位置，请在 `~/.raven/.env` 中设置 `SERVER_TOOLS_BIN=/path/to/dir`。
### 客户端中未加载 MCP 服务器
1. 验证服务器工作：`echo '{}' | node packages/jira-mcp/dist/index.js`（不应崩溃，从 `raven/` 目录运行）
2. 检查您的 MCP 配置中的路径是否绝对并包含 `raven/` 子目录
3. 如果需要，请重新构建：`cd raven && npm run build`
### 模型性能缓慢
参见 [Ollama 性能调优](#ollama-performance-tuning)。考虑为日常任务使用 7B 模型。
## 许可
Copyright 2026 Province of British Columbia
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
## Copilot 说明和 AI 代理行为
此仓库包含一个 `.github/copilot-instructions.md` 文件，定义了 GitHub Copilot Chat 和其他 Copilot 支持的代理如何与 RAVEN MCP 服务器交互。这些说明：
- 记录所有可用的工具和工作流程（Jira、Confluence、Bitbucket、服务器监视器、IMIS、资产、健康分析等）
- 强制执行安全、隐私和操作防护措施（例如 FOIPPA 合规性、个人身份信息擦除、禁止破坏性操作）
- 描述常见任务的工具链接模式（错误调查、票证创建、投资组合健康状况等）
- 指定门票编写、PR 和代码更改的约定
如果您使用 Copilot Chat 或任何支持 MCP 的 AI 客户端，这些说明可确保安全、可预测和合规的自动化。您可以查看或自定义 `.github/copilot-instructions.md` 中的它们。
### 使说明在全球范围内可用
默认情况下，`.github/copilot-instructions.md` 仅在 RAVEN 文件夹作为 VS Code 工作区根目录时生效。要在**每个**工作区加载 RAVEN 说明（例如，在处理 `nr-rrs` 或其他项目时），请将以下内容添加到 VS Code 用户 `settings.json`（**⌘⇧P** → "打开用户设置 JSON"）：
```json
"github.copilot.chat.codeGeneration.instructions": [
{
"file": "/path/to/raven/.github/copilot-instructions.md"
}
]
```
将 `/path/to/raven` 替换为您的实际克隆路径。这告诉 Copilot 无论您打开哪个项目，都始终包含 RAVEN 工具说明 — 这很有用，因为您通常希望在处理完全不同的仓库时查询 Jira 或搜索日志。
> **注意：** 本仓库仅供内部 BC Gov NR Sector 使用。不得用于公共分发或外部采用。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器