strands-agents/mcp-server 完整教學

1claude mcp add strands uvx strands-agents-mcp-server

 1{
 2  "mcpServers": {
 3    "strands-agents": {
 4      "command": "uvx",
 5      "args": ["strands-agents-mcp-server"],
 6      "env": {
 7        "FASTMCP_LOG_LEVEL": "INFO"
 8      },
 9      "disabled": false,
10      "autoApprove": ["search_docs", "fetch_doc"]
11    }
12  }
13}

1{
2  "servers": {
3    "strands-agents": {
4      "command": "uvx",
5      "args": ["strands-agents-mcp-server"]
6    }
7  }
8}

 1{
 2  "mcpServers": {
 3    "strands-agents": {
 4      "command": "uvx",
 5      "args": ["strands-agents-mcp-server"],
 6      "env": {
 7        "FASTMCP_LOG_LEVEL": "INFO"
 8      },
 9      "disabled": false,
10      "autoApprove": ["search_docs", "fetch_doc"]
11    }
12  }
13}

 1{
 2  "mcpServers": {
 3    "strands-agents": {
 4      "command": "uvx",
 5      "args": ["strands-agents-mcp-server"],
 6      "env": {
 7        "FASTMCP_LOG_LEVEL": "INFO"
 8      },
 9      "disabled": false,
10      "autoApprove": ["search_docs", "fetch_doc"]
11    }
12  }
13}

1# 用已發佈的 PyPI 套件測試
2npx @modelcontextprotocol/inspector uvx strands-agents-mcp-server
3
4# 用本地開發版本測試
5npx @modelcontextprotocol/inspector python -m strands_mcp_server

 1# 1. Clone repo
 2git clone https://github.com/strands-agents/mcp-server.git
 3cd mcp-server/strands-mcp
 4
 5# 2. 建立虛擬環境並安裝（含開發依賴）
 6python3 -m venv venv
 7source venv/bin/activate
 8pip3 install -e ".[dev]"
 9
10# 3. 用 Inspector 測試
11npx @modelcontextprotocol/inspector python -m strands_mcp_server
12
13# 4. 執行測試
14pytest tests/                     # 單元測試（不需網路）
15pytest tests_integ/ -v            # 整合測試（需網路）
16pytest tests/ tests_integ/ -v     # 全部測試

 1# 當 AI 助手收到使用者問題：「如何在 Strands Agents 中使用 Bedrock 模型？」
 2# AI 會呼叫 search_docs tool：
 3
 4result = search_docs(query="bedrock model provider", k=5)
 5
 6# 回傳結果結構（範例）：
 7# [
 8#     {
 9#         "url": "https://strandsagents.com/.../bedrock/",
10#         "title": "Amazon Bedrock",          # 策展標題（來自 llms.txt）
11#         "score": 0.847,                      # 相關性分數（0-1，越高越相關）
12#         "snippet": "Amazon Bedrock provides  # 內容預覽（最多 300 字元）
13#                     access to foundation..."
14#     },
15#     {
16#         "url": "https://strandsagents.com/.../model-providers/",
17#         "title": "Model Providers",
18#         "score": 0.623,
19#         "snippet": "Strands Agents supports multiple model providers..."
20#     },
21#     ...
22# ]

 1# indexer.py 中的評分權重（由高到低）：
 2
 3# 1. 標題匹配 — 權重最高
 4#    - 未載入內容的文件：8 倍加權（補償 content 為空的情況）
 5#    - 短頁面（<800 字元）：5 倍加權
 6#    - 長頁面：3 倍加權
 7title_tf = title_lower.count(token) * _title_boost_for(doc)
 8
 9# 2. 標題匹配 (Header) — 4 倍加權
10#    Markdown 的 # ~ ###### 標題行
11header_tf += header.lower().count(token) * 4
12
13# 3. 程式碼區塊 — 2 倍加權
14#    ``` 包圍的程式碼和 ` 包圍的行內程式碼
15code_tf += code.lower().count(token) * 2
16
17# 4. 連結文字 — 2 倍加權
18#    [連結文字](url) 中的連結文字部分
19link_tf += link.lower().count(token) * 2
20
21# 5. 一般文字 — 1 倍（基本權重）
22content_tf = content_lower.count(token)

 1# 步驟一：先用 search_docs 找到相關 URL
 2# 步驟二：取得文件的目錄結構（不傳 section 參數）
 3
 4result = fetch_doc(uri="https://strandsagents.com/latest/user-guide/concepts/agents/agent-loop/")
 5
 6# 回傳結構（TOC 模式）：
 7# {
 8#     "url": "https://strandsagents.com/.../agent-loop/",
 9#     "title": "Agent Loop",
10#     "preamble": "The agent loop is the core execution cycle...",  # 前言文字
11#     "sections": [
12#         {
13#             "id": "1",
14#             "level": 2,
15#             "title": "How It Works",
16#             "summary": "The agent loop processes user messages through...",
17#             "children": [
18#                 {"id": "1.1", "title": "Message Processing"},
19#                 {"id": "1.2", "title": "Tool Execution"}
20#             ]
21#         },
22#         {
23#             "id": "2",
24#             "level": 2,
25#             "title": "Configuration",
26#             "summary": "You can configure the agent loop behavior...",
27#             "children": []
28#         }
29#     ]
30# }

 1# 步驟三：根據 TOC 的 section ID 讀取特定段落
 2
 3result = fetch_doc(
 4    uri="https://strandsagents.com/latest/user-guide/concepts/agents/agent-loop/",
 5    section="1.2"   # 讀取 "Tool Execution" 子段落
 6)
 7
 8# 回傳結構（Section 模式）：
 9# {
10#     "url": "https://strandsagents.com/.../agent-loop/",
11#     "title": "Agent Loop",
12#     "section_id": "1.2",
13#     "section_title": "Tool Execution",
14#     "content": "### Tool Execution\n\nWhen the model decides to use a tool..."
15# }

 1# 不傳 URI 時，回傳所有可用文件的完整清單
 2
 3result = fetch_doc()  # uri="" (預設)
 4
 5# 回傳結構：
 6# {
 7#     "urls": [
 8#         {"url": "https://strandsagents.com/.../quickstart/", "title": "Quickstart"},
 9#         {"url": "https://strandsagents.com/.../agent-loop/", "title": "Agent Loop"},
10#         {"url": "https://strandsagents.com/.../bedrock/", "title": "Amazon Bedrock"},
11#         ... (所有策展文件)
12#     ]
13# }

 1# 對於小於 8KB 的文件，伺服器自動回傳完整內容，跳過分段機制
 2
 3result = fetch_doc(uri="https://strandsagents.com/latest/some-short-page/")
 4
 5# 回傳結構（小型文件模式）：
 6# {
 7#     "url": "https://strandsagents.com/.../some-short-page/",
 8#     "title": "Quick Config",
 9#     "document_small": true,       # 標記為小型文件
10#     "reason": "size",             # 或 "no_sections"（無可解析段落）
11#     "content": "# Quick Config\n\nSet the following..."  # 完整內容
12# }

1# config.py 中的預設設定：
2llm_texts_url: list[str] = field(
3    default_factory=lambda: ["https://strandsagents.com/llms.txt"]
4)

1# Strands Agents Documentation
2
3## User Guide
4- [Quickstart](https://strandsagents.com/latest/quickstart/)
5- [Agent Loop](https://strandsagents.com/latest/user-guide/concepts/agents/agent-loop/)
6...

1# indexer.py 的五層加權 haystack：
2haystack_parts = [
3    title_text,           # 標題（含變體詞）— 最高權重
4    headers.lower(),      # ## 和 ### 標題行 — 高權重
5    link_text.lower(),    # [文字](url) 中的文字 — 中等權重
6    code_blocks.lower(),  # ``` 程式碼區塊 — 中等權重
7    inline_code.lower(),  # `行內程式碼` — 中等權重
8    content,              # 一般文字 — 基本權重
9]

 1# text_processor.py — index_title_variants()
 2def index_title_variants(display_title: str, url: str) -> str:
 3    # 原始標題
 4    base = display_title                     # "Agent2Agent"
 5    
 6    # 數字轉文字變體
 7    variant = re.sub(r"(?i)(\w)2(\w)",
 8                     r"\1 to \2", base)      # "Agent to Agent"
 9    
10    # URL slug 變體
11    slug = title_from_url(url)               # "Agent2agent" (from URL path)
12    
13    # 合併為搜尋用字串（去重）
14    return "Agent2Agent Agent to Agent Agent2agent"

 1# text_processor.py — make_snippet()
 2def make_snippet(page, display_title, max_chars=300):
 3    # 1. 移除 ``` 程式碼區塊
 4    text = _CODE_FENCE.sub("", text)
 5    
 6    # 2. 跳過標題行（# 開頭）
 7    # 3. 跳過與 display_title 重複的第一行
 8    # 4. 跳過項目清單（- * 1. 開頭）
 9    
10    # 5. 收集第一段有意義的散文
11    #    至少 120 字元或以句號結尾才算完整
12    if len(" ".join(buf)) >= 120 or line.endswith("."):
13        paras.append(" ".join(buf))
14        break
15    
16    # 6. 截斷至 300 字元，加省略號
17    return _truncate(snippet, max_chars)

1# server.py
2def _is_valid_doc_url(uri: str) -> bool:
3    parsed = urlparse(uri)
4    return parsed.scheme == "https" and parsed.hostname == "strandsagents.com"

1# doc_fetcher.py
2def _html_to_text(raw_html: str) -> str:
3    stripped = _HTML_BLOCK.sub("", raw_html)  # 移除 <script>/<style>
4    stripped = _TAG.sub(" ", stripped)          # 移除所有 HTML tag
5    stripped = html.unescape(stripped)          # 反轉 HTML entities
6    lines = [ln.strip() for ln in stripped.splitlines()]
7    return "\n".join(ln for ln in lines if ln)

 1{
 2  "tools": [
 3    {
 4      "name": "search_docs",
 5      "description": "Search curated documentation and return ranked results with snippets.",
 6      "inputSchema": {
 7        "type": "object",
 8        "properties": {
 9          "query": {"type": "string", "description": "Search query string"},
10          "k": {"type": "integer", "default": 5, "description": "Max results to return"}
11        },
12        "required": ["query"]
13      }
14    },
15    {
16      "name": "fetch_doc",
17      "description": "Read documentation pages with smart sectioning for token efficiency.",
18      "inputSchema": {
19        "type": "object",
20        "properties": {
21          "uri": {"type": "string", "default": "", "description": "Document URL"},
22          "section": {"type": "string", "default": "", "description": "Section ID from TOC"}
23        }
24      }
25    }
26  ]
27}

 1開發者的 AI 助手
 2    │
 3    ├── MCP Server (本專案)
 4    │   └── 查閱文件 → 生成正確的 Strands Agents 程式碼
 5    │
 6    ├── sdk-python / sdk-typescript
 7    │   └── 開發者實際寫 agent 用的 SDK
 8    │
 9    ├── tools
10    │   └── Agent 使用的內建工具（MCP Server 知道這些工具的文件在哪）
11    │
12    └── samples
13        └── 範例程式碼（MCP Server 索引這些範例）

1品味評分：🟢 好品味
2
3理由：
4- 設計極簡：只有 2 個 tool、6 個模組檔案、2 個依賴
5- 問題定義精準：不做通用文件伺服器，只做 Strands Agents 的文件伺服器
6- 效率導向：lazy loading + section-based browsing + 小文件自動全文回傳
7- 安全預設：URL 白名單 + 唯讀操作
8- 零配置：開箱即用，不需要使用者理解內部原理

 1strands-agents/mcp-server/
 2├── .github/
 3│   ├── CODEOWNERS
 4│   ├── dependabot.yml
 5│   └── workflows/
 6│       ├── mcp-pr-and-push.yml        # PR 和 push 時的 CI
 7│       ├── mcp-pypi-publish-on-release.yml  # Release 時自動發佈到 PyPI
 8│       └── mcp-test-lint.yml           # 測試和 lint
 9└── strands-mcp/                        # 主要套件目錄
10    ├── pyproject.toml                  # 套件設定 + 依賴
11    ├── CODE_OF_CONDUCT.md
12    ├── CONTRIBUTING.md
13    ├── LICENSE                         # Apache-2.0
14    ├── NOTICE
15    ├── README.md
16    ├── .pre-commit-config.yaml
17    ├── src/strands_mcp_server/
18    │   ├── __init__.py
19    │   ├── __main__.py                 # python -m 入口
20    │   ├── config.py                   # 全域設定（llms.txt URL、timeout）
21    │   ├── server.py                   # FastMCP 應用 + tool 定義
22    │   └── utils/
23    │       ├── __init__.py
24    │       ├── cache.py                # 全域快取 + 懶載入管理
25    │       ├── doc_fetcher.py          # HTTP 抓取 + HTML 清理
26    │       ├── indexer.py              # TF-IDF 搜尋引擎
27    │       └── text_processor.py       # Markdown 解析 + snippet 產生
28    ├── tests/
29    │   ├── conftest.py
30    │   ├── test_server.py
31    │   └── test_text_processor.py
32    └── tests_integ/
33        ├── __init__.py
34        ├── conftest.py
35        ├── test_fetch_doc.py
36        └── test_parse_pipeline.py