内容
# H1B MCP
[](https://pypi.org/project/h1b-mcp/)
[](https://pypi.org/project/h1b-mcp/)
[](LICENSE)
[](src/h1b_mcp/py.typed)
实时H-1B赞助检查，适用于Codex和其他MCP兼容代理。
`h1b-mcp`在真实浏览器中打开H1BGrader，搜索公司、职位名称和地点，提取配置文件表格，并返回具有结构化证据的标准化赞助信号。
> 这是一个独立的社区项目。它与H1BGrader无关、未经授权、不受其认可或赞助。
## 功能
- 通过SeleniumBase UC模式实时查找H1BGrader公司、职位名称和地点。
- 结构化的H-1B赞助信号：`强信号`、`混合信号`、`弱信号`或`无赞助`。
- 解析年度LCA批准和拒绝计数。
- 解析年度LCA批准率和拒绝率。
- 解析年度USCIS H-1B批准和拒绝计数。
- 解析年度USCIS批准率和拒绝率。
- 解析年度H-1B薪资最大值、中位数、平均值和最小值。
- 解析H1BGrader评分、置信度、年度评分和评分洞察卡。
- 解析最新的H-1B职位名称计数和薪资范围。
- 解析职位名称和地点聚合配置文件，包括顶级雇主、LCA趋势、批准率和薪资历史。
- 本地缓存，以便重复检查可以重用解析的H1BGrader数据。
- 类型化的Pydantic响应模型，易于代理使用。
- 浏览器阻止感知行为，引发清晰的工具错误，而不是构造赞助结论。
## 包含的工具
所有工具都返回类型化的结构化内容。MCP客户端可以通过`tools/list`检查完整的输入和输出模式。
### 公司工具
| 工具 | 用途 |
| --- | --- |
| `check_h1b_sponsorship` | 分类公司级H-1B赞助证据。 |
| `check_company_job_sponsorship` | 检查公司是否为特定职位名称提供赞助证据。 |
| `get_company_role_sponsorship_context` | 为角色组合公司特定和市场范围的H-1B上下文。 |
| `get_company_profile` | 返回完整的解析公司配置文件，以便进行更广泛的代理推理。 |
| `get_company_job_titles` | 返回公司的赞助职位名称。 |
| `get_company_lca_trends` | 返回公司的年度LCA批准和拒绝趋势。 |
| `get_company_uscis_trends` | 返回公司的年度USCIS批准和拒绝趋势。 |
| `get_company_salaries` | 返回公司的年度H-1B薪资历史。 |
| `get_company_grade` | 返回公司的H1BGrader评分详细信息。 |
### 职位名称工具
| 工具 | 用途 |
| --- | --- |
| `check_h1b_job_title_sponsorship` | 分类市场级H-1B赞助证据，为职位名称提供。 |
| `get_h1b_job_title_profile` | 返回完整的解析职位名称配置文件，以便进行更广泛的代理推理。 |
| `get_h1b_job_title_employers` | 返回职位名称的顶级H-1B赞助雇主。 |
| `get_h1b_job_title_lca_trends` | 返回职位名称的年度LCA批准和拒绝趋势。 |
| `get_h1b_job_title_salary` | 返回职位名称的年度H-1B薪资历史。 |
### 地点工具
| 工具 | 用途 |
| --- | --- |
| `check_h1b_location_sponsorship` | 分类城市级H-1B赞助证据。 |
| `get_h1b_location_profile` | 返回完整的解析城市配置文件，以便进行更广泛的代理推理。 |
| `get_h1b_location_employers` | 返回城市的顶级H-1B赞助雇主。 |
| `get_h1b_location_lca_trends` | 返回城市的年度LCA批准和拒绝趋势。 |
| `get_h1b_location_salary` | 返回城市的年度H-1B薪资历史。 |
## MCP客户端设置
前提条件：[安装uv](https://docs.astral.sh/uv/getting-started/installation/)，使`uvx`可用。
在MCP兼容的客户端中使用`h1b-mcp`。以下示例使用`uvx`运行发布的PyPI软件包。
查找使用SeleniumBase UC模式。第一个查找可能会自动下载或准备兼容的ChromeDriver。
### Codex
将服务器添加到Codex MCP配置中：
```toml
[mcp_servers.h1b]
command = "uvx"
args = ["h1b-mcp@latest"]
env = { UV_HTTP_TIMEOUT = "300" }
tool_timeout_sec = 300
```
或从CLI添加：
```bash
codex mcp add h1b --env UV_HTTP_TIMEOUT=300 -- uvx h1b-mcp@latest
```
重启Codex并检查`/mcp`以确认服务器可用。
### Claude Desktop和Claude Code
将服务器添加到Claude Desktop或Claude Code MCP配置中。此相同的stdio形状也适用于许多其他MCP兼容客户端：
```json
{
"mcpServers": {
"h1b": {
"command": "uvx",
"args": ["h1b-mcp@latest"],
"env": {
"UV_HTTP_TIMEOUT": "300"
}
}
}
}
```
或从Claude Code添加：
```bash
claude mcp add --env UV_HTTP_TIMEOUT=300 --transport stdio h1b -- uvx h1b-mcp@latest
```
保存配置并完全重启MCP客户端以启动服务器。
### VS Code
通过`MCP：添加服务器`添加服务器，或将其添加到`.vscode/mcp.json`：
```json
{
"servers": {
"h1b": {
"type": "stdio",
"command": "uvx",
"args": ["h1b-mcp@latest"],
"env": {
"UV_HTTP_TIMEOUT": "300"
}
}
}
}
```
## 本地开发设置
安装依赖项：
```bash
uv sync
```
在本地运行服务器：
```bash
uv run h1b-mcp
```
在发布之前，从Codex使用本地checkout：
```toml
[mcp_servers.h1b]
command = "uv"
args = ["run", "--project", "/path/to/h1b-mcp", "h1b-mcp"]
tool_timeout_sec = 300
```
## 用法
要求MCP客户端检查公司：
```text
检查Databricks是否赞助H-1B签证。
```
MCP工具调用：
```python
check_h1b_sponsorship(company_name="Databricks")
```
示例响应形状：
```json
{
"company_query": "Databricks",
"matched_company": "Databricks Inc",
"signal": "强信号",
"url": "https://h1bgrader.com/h1b-sponsors/databricks-inc-nokpn1vn04",
"evidence": [
"最新LCA表格报告2026财年有174份申请，包括173份获批和0份拒绝。",
"最新的非空USCIS表格行报告2025财年有337份批准和0份拒绝。",
"H1BGrader评分选项卡显示最新的A级评分，置信度高。",
"职位名称表格包括56个赞助职位行。"
]
}
```
## 工作原理
<details>
<summary>查看请求流程图</summary>
```mermaid
flowchart TD
A[MCP客户端调用任何H1B工具] --> B[FastMCP工具处理程序]
B --> C[tools.common run_tool or run_profile_tool]
C --> D[H1BGraderService]
D --> E{配置文件类型}
E --> F[get_company_profile]
E --> G[get_job_title_profile]
E --> H[get_location_profile]
F --> I{缓存条目新鲜？}
G --> I
H --> I
I -->|是| J[从实体缓存加载类型化配置文件]
I -->|否| K[H1BGraderClient fetch_profile with lookup spec]
K --> L[启动SeleniumBase UC首页会话]
L --> M[打开公司、职位名称或城市搜索选项卡]
M --> N[在共享类型搜索中输入查询]
N --> O[单击选定的下拉结果]
O --> P[打开查找规范所需的配置文件选项卡]
P --> Q[将页面源解析为类型化配置文件模型]
Q --> R[将配置文件写入匹配的缓存]
J --> S[聚焦响应生成器]
R --> S
S --> T{请求切片}
T --> U[赞助信号]
T --> V[角色上下文]
T --> W[完整配置文件]
T --> X[雇主或职位名称]
T --> Y[LCA或USCIS趋势]
T --> Z[薪资或评分]
U --> AA[返回结构化Pydantic输出]
V --> AA
W --> AA
X --> AA
Y --> AA
Z --> AA
K --> AB{Cloudflare或查找失败？}
AB -->|浏览器阻止或查找失败| AC[引发MCP工具错误并显示清晰的消息]
```
</details>
1. FastMCP工具接收公司、职位名称或地点请求。
2. 共享工具运行器创建一个`H1BGraderService`，并通过MCP上下文记录进度。
3. 服务选择匹配的配置文件缓存并检查解析的配置文件是否新鲜。
4. 在缓存命中时，类型化的缓存配置文件直接进入响应生成器。
5. 在缓存未命中时，SeleniumBase UC客户端打开H1BGrader并为请求的实体类型运行查找规范。
6. 查找规范选择正确的搜索选项卡、类型搜索输入、预期URL模式、要打开的选项卡和解析器。
7. 解析器提取可用的LCA、USCIS、薪资、评分、职位名称或雇主数据到类型化的配置文件模型中。
8. 服务将解析的配置文件存储在匹配的本地缓存中，以供后续工具调用。
9. 请求的工具从同一个缓存配置文件数据中构建一个聚焦的Pydantic响应。
10. 浏览器阻止、缺少建议和意外的查找失败被作为MCP工具错误引发，并带有清晰的消息。
## 信号
| 信号 | 含义 |
| --- | --- |
| `强信号` | 配置文件包含最近的结构化批准或提交证据。 |
| `混合信号` | 配置文件包含赞助和拒绝/无赞助指标。 |
| `弱信号` | 配置文件具有有限的赞助证据。 |
| `无赞助` | H1BGrader表明公司不是赞助商或未找到有用的配置文件数据。 |
## 浏览器阻止
H1BGrader仍可能出现人为验证、速率限制或其他机器人保护。当发生这种情况时，`h1b-mcp`引发MCP工具错误并显示清晰的消息，而不是根据内存中的主张。
浏览器配置文件和缓存存储在：
```text
~/.h1b-mcp/browser-profile
~/.h1b-mcp/cache/company-profiles
~/.h1b-mcp/cache/job-title-profiles
~/.h1b-mcp/cache/location-profiles
```
## 当前范围
该项目公开了由本地缓存的解析H1BGrader配置文件支持的公司、职位名称和地点工具。它不附带捆绑的雇主数据库或批量抓取H1BGrader。H-1B源数据定期发布，因此缓存的配置文件数据通常适用于重复分析，而不是分钟级的更新。
## 故障排除
| 问题 | 尝试方法 |
| --- | --- |
| 第一次查找速度慢 | 等待SeleniumBase准备ChromeDriver和浏览器配置文件。 |
| 工具超时 | 将MCP客户端的`tool_timeout_sec`增加到`300`。 |
| 工具报告浏览器阻止或查找错误 | 稍后重试或在H1BGrader上手动验证。服务器故意避免猜测。 |
| 本地服务器无法启动 | 运行`uv sync`，然后重试`uv run h1b-mcp`。 |
## 开发
运行正常的检查：
```bash
uv run ruff check .
uv run pyright
uv run pytest
uv build
```
仅运行测试：
```bash
uv run pytest -q
```
## 项目结构
```text
.
├── .github/workflows/
│ └── publish.yml # 构建、发布和PyPI发布工作流
├── src/h1b_mcp/
│ ├── h1bgrader/ # SeleniumBase浏览器客户端和查找规范
│ ├── matchers/ # 本地匹配助手，例如职位名称匹配
│ ├── models/ # Pydantic配置文件、响应和错误模型
│ ├── parsers/ # H1BGrader表格、评分、摘要和聚合解析器
│ ├── responses/ # 缓存配置文件的工具响应生成器
│ ├── tools/ # 按实体类型注册的FastMCP工具
│ ├── cache.py # 解析配置文件的通用磁盘缓存
│ ├── service.py # 缓存/获取协调层
│ ├── server.py # FastMCP服务器入口点
│ └── settings.py # 运行时路径、超时和缓存设置
├── tests/ # 解析器、缓存、响应和MCP服务器测试
├── pyproject.toml # 包元数据、依赖项和工具配置
└── uv.lock # 锁定依赖图
```
## 版本控制
版本提升使用`bumpver`:
```bash
uv run bumpver update --patch --no-fetch
uv lock
```
根据需要使用`--minor`、`--major`或`--set-version 1.2.3`而不是`--patch`。 `bumpver`配置为不创建提交、标签或推送。
