Web Serch MCP工具
此MCP服务器具有许多可用于与Web搜索和网站内容交互的工具
约定承诺Enabbled：
\[构建、杂务、ci、文档、壮举、修复、性能、重构、恢复、样式、测试\]\[类型枚举\]
例子：
build: fix the build使用 web_search 工具
输入参数：
query（string，必填）：搜索查询。max_results（整数，可选）：返回的最大结果数（1-10，默认为10）。
输出项示例：
{
"title": "Example Result Title",
"url": "https://example.com",
"snippet": "Short preview text from the result"
}
``;
### Testing
This project uses `pytest` and `pytest-asyncio`.
Run the test suite:
pytest-q
Continuous Integration is configured via GitHub Actions to run tests on every push and pull request.
### Configuration
- `LOG_LEVEL` — controls verbosity (e.g., `DEBUG`, `INFO`, `WARNING`).
### CI
A GitHub Actions workflow (`.github/workflows/ci.yml`) installs dependencies and runs the tests on `push` and `pull_request`. To require passing tests before merging, enable branch protection rules in your repository settings and require the workflow to succeed.
### License
MIT or your preferred license. Update this section as needed.
## Deployment (AWS CDK → AWS Lambda)
This repo includes an optional Continuous Deployment (CD) workflow that deploys the project as an internal AWS Lambda function using AWS CDK (Python). The Lambda is named `web_search_mcp` and invokes the existing `web_search_impl` logic via `src/lambda_handler.py`.
What gets provisioned:
- AWS Lambda function: `web_search_mcp` (Python 3.11)
- No public API; for internal invocation only (e.g., via EventBridge, other Lambdas, or manual invocation)
### Event format (Lambda)
Invoke the function with a JSON payload like:
{ “query”：“chatgpt”， “最大结果”：5 }
The response mirrors the dict returned by `web_search_impl`:
{ “query”：“chatgpt”， “结果”：〔{“标题”：“…”，“网址”：“.”，“代码段”：“..”}，…\]， “错误”：\[\] }
### CDK project layout
- `cdk/app.py` — CDK entrypoint
- `cdk/web_search_mcp_stack.py` — defines the Lambda (no API Gateway)
- `cdk/requirements.txt` — CDK Python dependencies
- `src/lambda_handler.py` — AWS Lambda entrypoint calling `web_search_impl`
- `src/requirements.txt` — minimal runtime deps bundled into the Lambda
### GitHub Actions CD (push to main)
- Workflow: `.github/workflows/cd.yml`
- Triggers: push to `main`
- Uses GitHub OIDC to assume an AWS IAM role
- Expects the following:
- Repo secret: `GH_AWS_ROLE_ARN` — ARN of the IAM role to assume
- Environment variables baked into the workflow: `AWS_ACCOUNT_ID` and `AWS_REGION`
Defaults in this repo:
- `AWS_ACCOUNT_ID=920096439137`
- `AWS_REGION=us-east-1`
You can change these by editing `.github/workflows/cd.yml`.
### One-time AWS setup (OIDC role)
You need an IAM role that GitHub Actions can assume via OpenID Connect. The simplest path is to create a role with trust policy for your GitHub repo and attach `AdministratorAccess` (tighten later).
1. Create an IAM role (e.g., `GitHubActionsDeployRole`) with the following trust policy, updating `repo: /` and branches as needed:
{ “版本”：“2012-10-17”， “声明”：\[ { “效果”：“允许”， “主体”：{“联合”：“arn:aws:iam:：${aws_ACCOUNT_ID}：oidc提供者/token.actions.github用户内容.com”}， “操作”：“sts：假设oleWithWebIdentity”， “条件”：{ “StringEquals”：{ “token.actions.github用户内容.com:aud”：“sts.amazonaws.com” }, “StringLike”：{ “token.actions.github用户内容.com:sub”：“repo：/：ref:refs/heads/main” } } } \] }
2. Attach permissions (start broad, then tighten):
- `AdministratorAccess` (for initial bootstrap and deployment)
3. In your GitHub repo settings, add a secret named `GH_AWS_ROLE_ARN` with the role's ARN.
### Deploy from CI
Push to `main`. The `deploy` workflow will:
1. Configure OIDC and assume the role (`GH_AWS_ROLE_ARN`).
2. Install CDK CLI and Python CDK deps.
3. `cdk bootstrap` your account/region (safe if already bootstrapped).
4. `cdk deploy` the `WebSearchMcpStack` without manual approval.
### Local synth/deploy (optional)
python-m pip安装--升级pip pip安装-r cdk/requirements.txt
设置环境（PowerShell示例）
$env:AWS_ACCOUNT_ID=“123456789” $env:AWS_REGION=“us-east-1”
在本地使用您配置的AWS凭据
cdk合成器 cdk部署
Notes:
- CDK bundles the Lambda from `src/` and installs `src/requirements.txt` into the artifact. Tests and dev-only files are not included.
- The MCP server code remains unchanged and is not started in Lambda; only `web_search_impl` is used via the handler.
## Releases, Versioning, and Deployment
This repo uses Conventional Commits + Semantic Release to automatically version, create GitHub Releases, and deploy the Lambda via CDK.
### Commit message rules (Conventional Commits)
- Major release: add `!` after type or include a `BREAKING CHANGE:` footer
- Example: `feat!: remove deprecated endpoint`
- Or:fix: adjust auth flow
BREAKING CHANGE: removed legacy token support
- Minor release: `feat: ...`
- Example: `feat(search): add max_results option`
- Patch release: `fix: ...` or `perf: ...`
- Example: `fix: handle empty query gracefully`
- Non-releasing by default: `docs:`, `chore:`, `ci:`, `build:`, `test:` (unless you add `!`)
Tip: To force a patch release without code changes, push an empty commit:切换到主分支 仅限git pull--ff git commit--allow空-m“修复：触发器释放” git 推送
### Pipeline flow
1. Push to `master` with Conventional Commit messages.
2. Workflow `tests` runs (lint commits + run tests). Must succeed.
3. Workflow `deploy (auto release + deploy)` triggers from the successful CI run and:
- Calculates next semver and publishes a GitHub Release tag `vX.Y.Z` with notes.
- Deploys that exact tag with CDK.
4. The Lambda is published as a new Lambda Version, with an Alias named like the tag (`v1-2-3`) and environment variable `APP_VERSION` set to the tag.
### Where to see results
- GitHub → Releases: new `vX.Y.Z` with notes and updated `CHANGELOG.md`.
- AWS Lambda → your function `web_search_mcp`:
- Versions: one per release, description includes `Release vX.Y.Z`.
- Aliases: `vX-Y-Z` pointing to its version.
- Environment: `APP_VERSION` set to release tag.
### Formatting and validation
- CI validates `.releaserc.json` has no UTF-8 BOM and is valid JSON.
- The repository includes `.editorconfig` enforcing UTF-8 (no BOM) and LF endings.