快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

命令预览

python3 -m venv .venv

详细介绍

MOS MCP服务器

我的Oracle支持通过模型上下文协议集成Claude代码

允许Claude Code自动访问的MCP服务器 我的Oracle支持（MOS） 搜索技术文档、支持说明和Oracle数据库问题的解决方案。

🔧 可用的MCP工具

此服务器公开 3工具 克劳德可以自动调用：

工具	说明	查看详细信息
🔍 `search_mos_knowledge`	在MOS知识库中搜索文章和技术说明（默认情况下最多返回6个结果，忽略补丁/错误）	参见示例
🎯 `diagnose_mos_issue`	使用AI进行智能诊断：搜索、阅读前3篇文章的全部内容、分析并可以向用户提问以完善诊断	参见示例
🔧 `find_patch_by_bug`	搜索与特定错误号相关的补丁	参见示例

______________________________________________________________________

✨ 特性

🔐 半自动2FA身份验证

- 使用用户名/密码自动登录 - 仅在必要时（第一次和会话到期时）请求2FA代码 - 持续会话（有效期数周） - 无需分享您的TOTP密钥 -更安全

🔍 MOS知识库搜索

- 仅在知识库中搜索（忽略补丁、错误和其他部分） - 默认情况下最多返回6个结果（可配置） - 自动点击“查看更多”以加载所有知识文章 - 从多种格式（\[ID XXXXX\]、KB等）中提取文档ID - 描述性标题提供了一目了然的上下文

🎯 智能AI驱动的诊断

- 搜索相关MOS文章（前3名） - 使用浏览器自动化读取每篇文章的全部内容 - 分析并推荐最多3个最相关的注释 - 可以向用户提问 完善诊断 - 提供可操作的指导，而不仅仅是列表

🔧 按错误号搜索补丁

- 对DBA修补工作流程至关重要 - 查找特定错误的补丁 - 与MOS贴片计划集成 - 安装说明的直接链接

🔒 凭证安全

- 凭据存储在本地 ~/.claude.json 具有限制性权限 - 通过环境变量进行配置(-e MOS_USERNAME=... -e MOS_PASSWORD=...) - 永远不要离开你的机器 - 遵循MCP标准

______________________________________________________________________

🚀 快速开始

通过Homebrew安装（推荐）

1. 添加MasOrange点击

brew tap masorange/tap

2. 安装MCP服务器

brew install mcp-mos

或者在一个命令中：

brew install masorange/tap/mcp-mos

3. 配置凭据

创建文件 ~/.mcp-mos.env 使用您的凭据：

cat > ~/.mcp-mos.env  ~/.mcp-mos.env  ~/.mcp-mos.env  **重要提示：** 凭据保存在Claude Code的本地配置文件中(`~/.claude.json`)并在会话之间持续

______________________________________________________________________

## 📋 运作原理

### 数据源

MCP服务器直接连接到 **我的Oracle支持** (https://support.oracle.com)使用：

- 🔐 使用用户名/密码+交互式2FA进行身份验证（控制台提示）
- 🌐 Playwright实现浏览器自动化
- 📊 从MOS知识库中提取内容

### 身份验证流程

User configures credentials in ~/.mcp-mos.env
Adds MCP server with: claude mcp add oracle-mos -e "MOS_USERNAME=..." -e "MOS_PASSWORD=..."
Credentials are saved in ~/.claude.json (local to project)
First time Claude calls MOS → MCP Server wakes up
Server logs in with user/pass → MOS asks for 2FA
YOU GET A PROMPT → Enter code from Oracle Authenticator
Session is saved → Valid for weeks
Subsequent uses → Uses saved session (no login, no 2FA)
If session expires → Asks for 2FA code again (step 6)


**安全说明：** 凭据存储在 `~/.claude.json` 具有限制性权限（只有您可以读取它们）。这 `~/.mcp-mos.env` 该文件仅用于简化初始配置。

______________________________________________________________________

## 🔄 技术流程

### 流程1： `search_mos_knowledge` -知识库搜索

┌─────────────────────────────────────────────────────────────┐ │ 1. User/Claude calls search_mos_knowledge("ORA-00600") │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 2. Open browser session (headless) │ │ - Check if already logged in (cookie check) │ │ - If not: Login with username/password + 2FA prompt │ │ - Save session for reuse │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 3. Navigate to MOS and perform search │ │ - Fill search box with query │ │ - Press Enter and wait for results │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 4. Click "View more" in Knowledge section │ │ - Loads ALL Knowledge articles (not just preview) │ │ - Waits for page to load completely │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 5. Extract article links with kmExternalId │ │ - Locate all links │ │ - Fallback to kmContentId if no kmExternalId found │ │ - Skip generic "Welcome" articles │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 6. Extract Doc ID from each article │ │ - Try [ID XXXXX] format │ │ - Try (KB#####) format │ │ - Extract from URL (kmExternalId/kmContentId) │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 7. Return up to N results (default: 6) │ │ {doc_id, title, url} │ └─────────────────────────────────────────────────────────────┘


**关键实施细节：**

- **单会话重用**：浏览器会话保持打开并经过身份验证
- **只关注知识**：显式搜索知识库，忽略补丁/错误
- **“查看更多”自动化**：确保加载所有结果，而不仅仅是预览（3个结果）
- **多种文档ID提取策略**：处理各种MOS格式
- **没有片段**：标题的描述性足以理解内容

______________________________________________________________________

### 流程2： `diagnose_mos_issue` -人工智能驱动的诊断

┌─────────────────────────────────────────────────────────────┐ │ 1. User/Claude calls diagnose_mos_issue( │ │ error="ORA-00600 KGHALP1", │ │ context="Running migrateDataToXml.sh..." │ │ ) │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 2. Build search query (CRITICAL: error only, NOT context) │ │ query = "ORA-00600 KGHALP1" │ │ ❌ WRONG: "ORA-00600 KGHALP1 Running migrateData..." │ │ (Context too specific → wrong results) │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 3. Open SINGLE browser session for entire operation │ │ ⚠️ CRITICAL: Do NOT open separate sessions! │ │ - Session 1 for search │ │ - Session 2 for get_article → FAILS (not authenticated) │ │ │ │ ✅ CORRECT: One session for search + get_article │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 4. Search for top 3 articles (using search flow above) │ │ results = await client.search(query, limit=3) │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 5. Read full content of each article (SAME session) │ │ for result in results[:3]: │ │ article = await client.get_article( │ │ doc_id=result['doc_id'], │ │ url=result['url'] ← Use search result URL │ │ ) │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 6. Extract content from each article page │ │ - Wait 5 seconds for page to fully render │ │ - Take screenshot for debugging (/tmp/mos_article_*.png) │ │ - Get all body text (robust, works with any layout) │ │ - Clean up whitespace │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 7. Return articles with full content to AI for analysis │ │ - Article 1: {doc_id, title, content, url} │ │ - Article 2: {doc_id, title, content, url} │ │ - Article 3: {doc_id, title, content, url} │ │ - + AI analysis instructions │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ 8. AI analyzes content and provides diagnosis │ │ - Identifies top 3 most relevant solutions │ │ - Explains relevance to specific issue │ │ - May ask diagnostic questions to narrow down │ └─────────────────────────────────────────────────────────────┘


**关键实施细节：**

- **仅搜索错误，不完整上下文**：防止返回错误结果的过于具体的查询
- **单一身份验证会话**：避免在搜索和文章阅读之间重新登录至关重要
- **使用搜索结果URL**：通行证 `url` 参数到 `get_article()` 正确导航
- **强大的内容提取**：获取所有正文，而不是尝试特定的选择器
- **等待时间更长**：5秒+网络空闲确保JavaScript内容呈现
- **调试截图**：已保存到 `/tmp/mos_article_{doc_id}.png` 故障排除
- **用于分析的上下文**：上下文帮助AI分析结果，而不是搜索查询

______________________________________________________________________

## 为何这很重要

- ⚡ **即时答案** Oracle错误
- 📚 **直接访问** 到官方知识库
- 🎯 **精确的建议** 基于真实的文档ID
- 🔒 **安全** -凭据仅保留在本地计算机上
- 📦 **简易安装** -与Homebrew和MCP标准兼容

______________________________________________________________________

## 🎯 用法

配置后，Claude可以自动使用这些工具：

### 1.🔍 搜索知识库(`search_mos_knowledge`)

**例子：**

User: "I have an ORA-00060 deadlock in production"

Claude: [Searches MOS Knowledge Base automatically]

🔍 MOS Search Results for: 'ORA-00060 deadlock' Found 6 articles:

How to Resolve ORA-00060 Deadlock Detected

Doc ID: 122020.1 URL: https://support.oracle.com/...

Interpreting Deadlock Graphs

Doc ID: 61998.1 URL: https://support.oracle.com/...


### 2.🎯 智能诊断(`diagnose_mos_issue`)

**例子：**

User: "I have ORA-01555 snapshot too old on my long queries"

Claude: [Searches, reads full articles and analyzes]

🎯 MOS Diagnostic Analysis

Issue: ORA-01555 snapshot too old on long queries Context: Oracle 19c, reporting queries

Found 8 articles, analyzed top 5:

Article 1: How to Avoid ORA-01555 During UNDO Management

Doc ID: 1555.1 URL: https://support.oracle.com/...

Content: ORA-01555 occurs when a query needs to read undo data that has been overwritten. This typically happens when:

UNDO_RETENTION is too small
Queries run for longer than undo retention period
High DML activity overwrites undo blocks

1. Patch 34567890: Fix for Memory Leak in RMAN

Doc ID: 2890123.1 URL: https://support.oracle.com/... Summary: This patch addresses a memory leak in RMAN backup operations affecting Oracle 19.15 and earlier...

2. Database Bundle Patch 19.22 (Includes Bug 34567890)

Doc ID: 2891234.1 URL: https://support.oracle.com/... Summary: Latest Bundle Patch for 19c includes fix for bug 34567890...

💡 Next Steps: Review the articles above to find the appropriate patch for your environment. Click on the URLs to access MOS and read full patch details and installation instructions.


______________________________________________________________________

## 🛠️ 项目结构

mos-mcp-server/ │ ├── README.md ← This file ├── LICENSE ← MIT License ├── pyproject.toml ← Modern project configuration (PEP 621) ├── requirements.txt ← Python dependencies ├── setup.py ← Python packaging ├── pytest.ini ← Test configuration ├── mcp-mos ← Main executable │ ├── .github/ ← GitHub templates │ ├── ISSUE_TEMPLATE/ │ │ ├── bug_report.md │ │ ├── feature_request.md │ │ ├── question.md │ │ └── config.yml │ └── pull_request_template.md │ ├── .gitignore ← Excludes credentials from git │ └── src/ ├── __init__.py ├── auth.py ← Credential management (env vars) ├── exceptions.py ← Custom exceptions ├── server.py ← Main MCP server (tool dispatcher) │ ├── client/ ← Functional MOS client (no mixins, clean architecture) │ ├── __init__.py ← MOSClient (composition over inheritance) │ ├── session.py ← Session management │ ├── login.py ← Pure login functions │ ├── search.py ← Pure search functions │ ├── article.py ← Pure article retrieval functions │ └── helpers.py ← Pure helper functions │ ├── handlers/ ← MCP tool handlers │ ├── __init__.py │ ├── base.py ← Common handler patterns │ ├── search.py ← search_mos_knowledge handler │ ├── diagnose.py ← diagnose_mos_issue handler │ └── patch.py ← find_patch_by_bug handler │ └── tests/ ← Unit tests ├── __init__.py └── test_auth.py

Note: The Homebrew formula is in a separate repository: https://github.com/masorange/homebrew-tap


______________________________________________________________________

## 🐛 故障排除

### ❌ “未配置MOS凭据”

**解决方案：**

核实一下 `~/.mcp-mos.env` 存在正确的变量：

cat ~/.mcp-mos.env


应包含：

MOS_USERNAME=your.email@company.com MOS_PASSWORD=your_password


如果它不存在，请创建它：

cat > ~/.mcp-mos.env << 'EOF' MOS_USERNAME=your.email@company.com MOS_PASSWORD=your_password EOF chmod 600 ~/.mcp-mos.env


### ❌ “无效代码。必须是6位数字”

**原因：**

- 2FA代码输入错误

**解决方案：**

1. 验证Oracle身份验证器中的代码（6位数字）
1. 出现提示时再次输入
1. 请确保在到期前输入（30秒）

### ❌ “ModuleNotFoundError”或“连接失败”

**可能的原因：**

- 不使用虚拟环境Python手动安装
- 缺少依赖项

**解决方案：**

如果您是手动安装的，请确保使用venv Python：

Verify server uses correct venv

claude mcp get oracle-mos

Should show: Command: /full/path/.venv/bin/python

If not, update:

claude mcp remove oracle-mos -s local source ~/.mcp-mos.env claude mcp add oracle-mos \ -e "MOS_USERNAME=${MOS_USERNAME}" \ -e "MOS_PASSWORD=${MOS_PASSWORD}" \ -- /full/path/to/mos-mcp-server/.venv/bin/python /full/path/to/mos-mcp-server/mcp-mos


### ❌ “登录失败”

**可能的原因：**

- Claude Code配置中的凭据不正确
- MOS更改了其接口（过时的CSS选择器）
- 网络/VPN问题

**解决方案：**

1. Verify saved credentials

claude mcp get oracle-mos

2. Update credentials if incorrect

nano ~/.mcp-mos.env

(then remove and re-add server, see "Change credentials" section)

3. Verify access to MOS

curl -I https://support.oracle.com


### ⏱️ 会话已过期

剧作家会话会自动保存。如果过期，只需再次使用Claude，系统会要求您提供2FA代码以续订。

### 🔄 更改凭据

要更新凭据，请执行以下操作：

1. Edit credentials file

nano ~/.mcp-mos.env

2. Update values

MOS_USERNAME=new.email@company.com

MOS_PASSWORD=new_password

3. Remove and re-add MCP server

claude mcp remove oracle-mos -s local

4. Load new variables and add server

source ~/.mcp-mos.env claude mcp add oracle-mos \ -e "MOS_USERNAME=${MOS_USERNAME}" \ -e "MOS_PASSWORD=${MOS_PASSWORD}" \ -- mcp-mos


______________________________________________________________________

## 🔧 高级配置

### 调试模式（可见浏览器）

编辑 `src/server.py` 或 `src/client.py`:

Change from:

client = MOSClient(headless=True)

To:

client = MOSClient(headless=False)


这将直观地打开浏览器，查看发生了什么。

**文件位置：**

- 如果与Homebrew一起安装：文件位于Homebrew的virtualenv中
- 如果手动安装： `src/server.py` 和 `src/client.py` 在您的安装目录中

### 调整CSS选择器

如果Oracle更改了MOS UI，则选择器可能需要更新。

**文件：** `src/client.py`

**常见选择器：**

Login

username_field = self.page.locator('input[type="text"][name*="username"]') password_field = self.page.locator('input[type="password"]') totp_field = self.page.locator('input[name*="otp"]')

Search

result_elements = self.page.locator('.search-result, article') title_elem = element.locator('h3, .title, a[href*="Doc"]')


### 更改超时

In src/client.py

self.page.wait_for_load_state("networkidle", timeout=60000) # 60s


______________________________________________________________________

## 🧪 测试

该项目包括使用pytest的单元测试：

Install dev dependencies

pip install -e ".[dev]"

Run tests

pytest

Run tests with coverage

pytest --cov=src --cov-report=html

View coverage report

open htmlcov/index.html


______________________________________________________________________

## 🤝 贡献

欢迎投稿！

### 改进空间

- 🔧 **CSS选择器**：如果Oracle更改了MOS，则选择器需要更新
- 📊 **内容提取**：改进文章解析
- 🎨 **格式化**：更好的结果展示
- ⚡ **演出**：优化搜索和缓存
- ✅ **测试**：添加更多测试覆盖率

### 如何做出贡献

1. 克隆该仓库
1. 创建分支(`git checkout -b feature/improvement`)
1. 安装开发依赖项： `pip install -e ".[dev]"`
1. 为您的更改编写测试
1. 确保测试通过： `pytest`
1. 提交您的更改(`git commit -am 'Add: new functionality'`)
1. 推到分支(`git push origin feature/improvement`)
1. 打开拉取请求

______________________________________________________________________

## 📝 许可证

该项目根据 **MIT许可证** -看看 [许可证](LICENSE) 文件以获取详细信息。


______________________________________________________________________

## 🔗 参考文献

- [模型上下文协议（MCP）](https://modelcontextprotocol.io/)
- [克劳德代码MCP文档](https://docs.anthropic.com/claude/docs/model-context-protocol)
- [剧作家Python](https://playwright.dev/python/)
- [我的Oracle支持](https://support.oracle.com/)
- [Oracle身份验证器](https://www.oracle.com/security/mobile-authenticator/)

______________________________________________________________________

## 👥 作者

**豪尔赫·利洛** - *初步工作* -MasOrange改装/MySIM团队

______________________________________________________________________

## 📈 版本

**v1.4.0版本** - 2026-02-11

### 更新日志

#### v1.4.0（2026-02-11）-功能重构和清理

- ♻️ **重构：** 遵循Python最佳实践完成架构重组
  - 消除了多重继承和混合（违反了Python的PEP 8和Zen）
  - 应用函数式编程：无副作用的纯函数
  - 贯穿始终的组合而非继承模式
  - 分体式单片 `client.py` （793行）分为6个模块化文件：
    - `session.py`：会话管理（简单类，无继承）
    - `login.py`：纯登录功能
    - `search.py`：纯搜索功能
    - `article.py`：纯文章检索功能
    - `helpers.py`：纯辅助函数
    - `__init__.py`：MOSClient使用组合
  - 将处理程序组织成单独的模块（搜索、诊断、补丁）
  - 添加 `exceptions.py` 用于集中异常处理
- 🗑️ **远离的：** `get_mos_article` 工具
  - 独立调用时存在持续的身份验证问题
  - 功能完全由 `diagnose_mos_issue` （效果很好）
  - 工具数量从4个减少到3个（更简单、更专注）
  - 删除199行死代码
- 📝 **改进：** 代码组织和可维护性
  - 每个模块都有单一的职责
  - 函数是无状态的，可测试的
  - 明确区分关注点
  - 遵循“简单胜于复杂”（Python禅宗）
  - 遵循“显式优于隐式”（Python禅宗）
- 📊 **韵律学：** 代码库从1285行（2个文件）减少到1247行（14个模块化文件）

#### v1.3.0（2026-02-11）-内容提取的关键修复

- 🐛 **固定的：** `diagnose_mos_issue` 身份验证问题
  - 现在使用单个MOSClient会话进行搜索+获取文章操作
  - 以前打开的单独会话导致登录失败
- 🐛 **固定的：** 搜索查询构建中 `diagnose_mos_issue`
  - 现在只搜索错误/问题（例如，“ORA-00600 KGHALP1”）
  - 上下文参数仅用于AI分析，不用于搜索
  - 防止返回错误结果的过于具体的查询
- 🐛 **固定的：** 文章内容提取 `get_article`
  - 将JavaScript渲染的等待时间延长至5秒
  - 简化提取：获取所有正文，而不是脆弱的CSS选择器
  - 添加了保存到的调试屏幕截图 `/tmp/mos_article_{doc_id}.png`
  - 同时支持kmExternalId和kmContentId URL格式
- 📖 **补充：** 技术流程文件
  - 显示每个操作如何在内部工作的详细图表
  - 每个流程的关键实施说明
  - 基于常见问题的故障排除指南

#### v1.2.0（2026-02-11）-以知识为中心的搜索

- 🔄 **重命名：** `search_mos` → `search_mos_knowledge` 为清晰起见
  - 现在只显式搜索知识库部分
  - 忽略补丁、错误和其他部分
  - **突破性变化：** 更新工具调用以使用新名称
- 🎯 **增强：** 搜索功能
  - 自动点击“查看更多”以加载所有知识文章
  - 默认限制：6个结果（共10个）
  - 改进的文档ID提取： `[ID XXXXX]`, `KB`, `kmExternalId` 格式
  - 删除片段（标题足够描述性）
- 🎯 **优化：** `diagnose_mos_issue`
  - 现在正好读到3篇文章（一致性为3-5）
  - 更快、更专注的分析
- 📸 **补充：** 带有9个屏幕截图的流程文档
  - 从登录到文档查看的完整视觉指南

#### v1.1.0（2026-02-10）-增强的DBA工作流程

- 🎯 **增强：** `diagnose_mos_issue` -交互式提问智能诊断
  - 阅读前3篇文章的全部内容
  - 人工智能分析最多关注3个最相关的笔记
  - **可以向用户提出诊断问题** 缩小解决方案的范围
  - 提供可操作的指导，而不仅仅是文章列表
- 🔧 **新** `find_patch_by_bug` -按错误号搜索补丁
  - 对DBA修补工作流程至关重要
  - 快速补丁查找与MOS补丁计划集成
  - 安装说明链接
- 🗑️ **远离的：** `list_service_requests` （Oracle有官方的服务请求MCP）

#### v1.0.0（2026年1月22日）

- ✨ 初始版本
- 🔐 半自动身份验证（交互式2FA）
- 🔍 MOS搜索功能
- 📄 按文档ID检索文章
- 🎯 智能推荐
- 🔒 基于环境变量的配置
- ✅ 无需TOTP密钥-更安全
- 📦 Homebrew安装支持
- 🛠️ 兼容 `claude mcp add` 命令

______________________________________________________________________

  Made with ❤️ by the Retrofit Team @ MasOrange

目录标签

PythonClaude搜索Oracle支持本地部署文档搜索数据库问题解决技术文档检索AI诊断

支持客户端

Claude

接入字段

传输方式（transport，传输协议）

stdio

鉴权方式（authType，认证方式）

session

运行时（runtime，运行环境）

Python

工具数量（toolCount，工具数）

3

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

stdiosession部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

来源信息

MCP World

mcpworld.com

/detail/497c178660eb25a435d666a30dd62ca9

通过Model Context Protocol为Claude Code提供My Oracle Support集成，自动搜索技术文档、支持说明和Oracle数据库问题解决方案。

继续浏览同类 MCP

更多搜索检索 MCP（7,303）返回 MCP 目录

上一个 MCP

Morpho MCP

A morpho server for the model context protocol

下一个 MCP

moss MCP

Moss MCP Server是一个基于Model Context Protocol（MCP）的服务器，用于管理高性能语义搜索索引，支持创建、列表和删除向量索引，以及文档的添加、更新和移除，适用于AI助手集成和快速语义搜索场景。

Mos MCP Server