Provides tools for searching and retrieving content from private GitHub Pages sites, including indexing site structure and enabling query-based access to page sections.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@GitHub Pages Retrieval MCP Find the row selection configuration in the Japanese table component"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
認証が必要なPrivate GitHub Pagesを、AIエージェントから検索するためのローカルMCPです。GitHub、SAML、MFAは専用ブラウザでユーザー自身が完了し、取得したページはローカルのSQLite索引から検索します。
このMCPはローカル実行専用です。Cloud Agentやクラウド上のコードレビューから、ユーザーPCの認証済みブラウザや索引を利用することはできません。
初回にサイトURLを受け取り、検索対象を自動設定
サイト内リンクをたどり、構成変更に追従して索引を更新
複数サイトと複数言語を個別または横断で検索し、必要な節だけ取得
Cookie、ページ本文、検索索引をユーザーPC内に保持
Related MCP server: search-docs
/plugin marketplace add ma-nakaya/github-pages-retrieval-mcp
/plugin install github-pages-retrieval@github-pages-retrieval-marketplacecopilot plugin marketplace add ma-nakaya/github-pages-retrieval-mcp
copilot plugin install github-pages-retrieval@github-pages-retrieval-marketplace初回起動時に、必要なNode.jsパッケージとPlaywright Chromiumを自動で導入します。
GitHub Pages検索用のAgent Skillを同梱しており、Claude CodeとGitHub Copilot CLIの両方から利用できます。
エージェントにPrivate Pagesの内容を調べるよう依頼します。
検索対象が未設定なら、エージェントがサイトURLを質問します。URLを回答すると、ソースID、許可オリジン、専用ブラウザプロファイルが自動設定されます。
認証が必要な場合はローカルブラウザが開きます。GitHub、SAML、MFAを完了し、エージェントに完了したことを伝えます。
初回またはサイト更新時に索引を作成します。その後はコンポーネント名、API名、設定項目などを通常の言葉で検索できます。
たとえば、次のように依頼できます。
このPrivate Pagesを検索対象にして:
https://example.github.io/private-docs/
日本語版のテーブルコンポーネントで、行選択の設定を調べてflowchart TD
A[ユーザーの質問] --> B{検索対象は設定済みか}
B -- いいえ --> C[サイトURLをユーザーに確認]
C --> D[ソースと許可オリジンを設定]
B -- はい --> E{認証は有効か}
D --> E
E -- いいえ --> F[専用ブラウザを開く]
F --> G[ユーザーがGitHub・SAML・MFAを完了]
G --> H{索引の作成・更新が必要か}
E -- はい --> H
H -- はい --> I[画面上のリンクを並列巡回]
I --> J[ページを見出し単位に分割]
J --> K[(ローカルSQLite索引)]
H -- いいえ --> L[サイト・言語・語句で検索]
K --> L
L --> M[URL・見出し・短いスニペット]
M --> N[選択した節だけ取得]
N --> O[根拠URLとともに回答]サイトマップには依存せず、画面上のナビゲーションリンクからページ構成を検出します。検索索引はローカルのSQLiteに保存し、サイト更新時だけ差分更新します。
検索結果はURL、見出し、短いスニペットを先に返し、必要な節だけ取得します。ページ全文を毎回モデルへ渡さないため、トークン消費を抑えられます。
ページ一覧は既定で50件ずつ返します。完全な一覧が必要な場合だけ次のページを取得し、通常の質問では一覧に頼らず索引全体を直接検索します。
複数サイトを登録できます。通常は対象サイトだけを検索し、横断検索を依頼した場合は全サイトからまとめて検索します。認証と索引更新はサイトごとに行います。
設定、ブラウザプロファイル、認証状態、検索索引は非公開のローカルディレクトリへ保存されます。Claude CodeはCLAUDE_PLUGIN_DATA、GitHub Copilot CLIはCOPILOT_PLUGIN_DATAとして提供する永続ディレクトリを利用します。手動起動時はGPR_PLUGIN_DATAで保存先を上書きできます。
アクセスするのは設定されたPagesオリジン内のHTMLページだけです。
ソースリポジトリ、GitHub API、外部の埋め込みサービスは利用しません。
パスワード、MFAコード、CookieをMCPツールへ入力しません。
日常利用のChromeプロファイルは使わず、サイトごとの専用プロファイルを作成します。
config.local.json、ブラウザプロファイル、検索索引をGitへコミットしないでください。
プラグイン更新後も認証状態を維持するには、プラグイン外の永続ディレクトリを指定してください。
Node.js 22.5以降を使用します。手動設定の例はconfig.example.jsonにあります。
npm install
npm test
npm startOpens a visible, persistent local browser at the configured GitHub Pages URL. The user completes GitHub, SAML, and MFA themselves.
| Name | Required | Description | Default |
|---|---|---|---|
| sourceId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It does disclose key behavioral traits: the browser is visible and persistent, and the user manually completes GitHub, SAML, and MFA steps. However, it does not mention what happens after the browser opens, whether the tool waits, or what response/status is returned, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the core action and user involvement. No filler or redundant information; every clause adds meaningful detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple (one param, no output schema), but the description omits critical contextual details: when to initiate reauth, what the sourceId parameter identifies, and what happens after the browser opens. This leaves the agent unclear about the tool's role in the broader authentication workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention the sourceId parameter at all. There is no explanation of what sourceId refers to or how it relates to the reauthentication flow. The description completely fails to compensate for the schema's lack of semantic detail, leaving the parameter's meaning only inferable from the tool name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: opens a visible, persistent local browser at the configured GitHub Pages URL for the user to complete reauthentication. It clearly implies the resource (source) and purpose (reauth), distinguishing it from sibling tools like get_source_auth_status or validate_source_auth, though it does not explicitly contrast them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as when a source's auth has expired or when to call validate_source_auth first. It only describes the action, not the appropriate context or preconditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persists a user-provided HTTPS Pages URL as a local search target, derives its exact origin allowlist, and creates a dedicated browser-profile path. Existing configuration is never replaced.
| Name | Required | Description | Default |
|---|---|---|---|
| sourceId | No | ||
| startUrl | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It states that the URL is 'persisted' and a browser-profile path is 'created', and importantly adds the non-destructive guarantee: 'Existing configuration is never replaced.' However, it does not mention auth prerequisites, error behavior, or return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences with no filler. The primary action is front-loaded, followed by the key invariant. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a clear overview of the operation and a notable behavioral guarantee, but it lacks usage context versus siblings and is silent on the optional 'sourceId'. Given no output schema and no annotations, this is adequate but leaves meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies that 'startUrl' is an HTTPS Pages URL, but it does not explain the optional 'sourceId' parameter or its validation pattern. Thus, only half of the parameters receive semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ("Persists", "derives", "creates") and clearly identifies the resource being configured (a Pages source) along with the concrete outcomes (origin allowlist, browser-profile path). This clearly differentiates it from sibling tools like 'list_pages_sources' or 'fetch_pages_content'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage for initial configuration of a Pages source but never explicitly states when to use it versus alternatives (e.g., 'validate_source_auth' or 'refresh_pages_index') or when not to use it. No exclusions or alternative tool mentions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns one cached page or exact heading/anchor with a strict character cap. Prefer a heading returned by search_pages_index to minimize tokens.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| heading | No | ||
| maxChars | No | ||
| sourceId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses caching behavior and a strict character cap, which go beyond the schema. However, it omits details about authentication, rate limits, error handling, and return format. It partially compensates but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, and every phrase earns its place. The first sentence states the core function, the second adds practical guidance without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no output schema, and no annotations, the description gives the essential idea and usage guidance. Yet it leaves sourceId's role and edge-case behavior unaddressed. It is adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains 'heading' (exact heading/anchor) and 'maxChars' (strict character cap), but sourceId and url are not semantically elaborated beyond their names. This is partial compensation, adequate but with clear gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Returns') and clearly identifies the resource ('one cached page or exact heading/anchor') with a distinct constraint ('strict character cap'). It distinguishes from sibling tools like search_pages_index (search vs retrieval) and fetch_pages_content (likely full content vs capped sections).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides direct usage context with 'Prefer a heading returned by search_pages_index to minimize tokens', indicating when to use this tool and how to choose the best input. However, it does not explicitly state when not to use it or directly contrast with the full-page fetching alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches one allowlisted GitHub Pages URL through its persistent local browser profile. It never reads the source repository.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| sourceId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing the use of a persistent local browser profile and explicitly stating it never reads the source repository. This gives useful behavioral context beyond the basic fetch action, though it omits details like return format or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences. The first delivers the core action, and the second adds a critical behavioral boundary. No unnecessary words or repeated schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core behavior and a key limitation are clear, but the description lacks parameter explanations, usage guidance, and return value expectations. Given no annotations and no output schema, the description is not fully complete for invoking the tool correctly in various contexts, though it covers the essentials.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about the 'url' or 'sourceId' parameters. The agent must guess their meanings from the schema alone, which only provides names and types but no semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches one allowlisted GitHub Pages URL using a persistent local browser profile. It also explicitly distinguishes itself by noting it never reads the source repository, which separates it from sibling tools that may access repositories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives like fetch_indexed_section or search_pages_index. The description implies a specific use case (fetching a direct URL) but lacks context for choosing it over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns index status, locale counts, and one page of a compact URL/title list. Use search_pages_index for named items; follow nextOffset only when a complete listing is required.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| locale | No | all | |
| offset | No | ||
| sourceId | Yes | ||
| pathContains | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool returns a page of results, includes index status and locale counts, and hints at pagination via nextOffset. While read-only nature is implied, the description offers solid behavioral context beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence states the outcome, the second gives usage alternatives and pagination advice. Excellent front-loading and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters and no output schema, but the description covers the output scope, pagination, and when to use an alternative. It lacks parameter-level detail and return format explanation, but given the moderate complexity, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it does not explain any parameter semantics. The description only implies that locale and pathContains might be filters, and limit/offset relate to pagination, but it leaves the agent to infer from parameter names and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool's purpose: returning index status, locale counts, and one page of a compact URL/title list. It also distinguishes itself from the sibling search_pages_index by directing named-item searches there, showing a specific verb+resource+scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use search_pages_index for named items, and follow nextOffset only when a complete listing is required. This clearly states when to use this tool vs alternatives and pagination behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the last known authentication state for a configured GitHub Pages source without exposing browser credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| sourceId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It implies a read-only operation via 'returns' and adds a useful security detail ('without exposing browser credentials'), but it does not explicitly state side-effect-free behavior, staleness of 'last known', or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no redundant information. Every phrase adds meaning, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with one parameter, it covers the main purpose and safety behavior. However, with no output schema, it omits the return format and does not address edge cases (e.g., source not found), leaving some ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not directly explain sourceId. It indirectly references it as 'a configured GitHub Pages source', but offers no format or additional context, leaving the parameter under-documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'returns' and identifies the resource as 'last known authentication state for a configured GitHub Pages source'. It clearly distinguishes from siblings like begin_source_reauth and validate_source_auth by being a status getter rather than a mutating or validation action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the sibling tools. It does not mention typical scenarios (e.g., checking status before re-auth) or explicitly exclude alternatives like validate_source_auth.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks whether any Pages search targets are configured. Call this before authentication or search so an agent can request a site URL when the list is empty.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden of disclosing behavior. It implies this is a read-only check, but doesn't state the return structure (e.g., list of URLs vs. boolean) or potential side effects. The line 'when the list is empty' hints at a list return, but this is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and includes actionable guidance without any redundancy. Every word contributes to understanding when and why to call the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (no parameters, no output schema), the description provides sufficient context for an agent to know when to call it and why. The only gap is the lack of explicit return value details, but the 'list is empty' phrasing partially covers this. Overall, adequate for a check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema already covers parameter semantics fully. The description correctly focuses on usage context rather than parameter details, which aligns with the baseline for tools with no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Checks' with a clear resource ('Pages search targets'), and the context of checking configuration distinguishes it from sibling tools like search_pages_index or configure_pages_source. The title also aligns, reinforcing the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit timing guidance ('Call this before authentication or search') and explains the benefit ('so an agent can request a site URL when the list is empty'). However, it does not mention alternatives or when not to use it, which would make it fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Starts a parallel background crawl of allowlisted rendered Pages links. Returns immediately; poll get_pages_index for compact progress and final statistics.
| Name | Required | Description | Default |
|---|---|---|---|
| maxPages | No | ||
| sourceId | Yes | ||
| concurrency | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does disclose that the crawl is background/parallel and that the function returns immediately, which is valuable. But it omits side effects (e.g., whether the old index is replaced), potential rate limits, and required permissions, leaving some behavioral uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, and no waste. The structure is ideal for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The high-level flow (start crawl, poll for progress) is covered, which helps for a simple trigger tool. However, the lack of parameter descriptions, failure mode information, and any auth note makes it incomplete for a tool with no output schema and no annotations. It is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention or explain any of the three parameters (sourceId, maxPages, concurrency). The agent is left to infer what these parameters do from names alone, which is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Starts a parallel background crawl') and the resource ('allowlisted rendered Pages links'), distinguishing it from sibling tools like get_pages_index and search_pages_index which are for reading/seaching the index. It also differentiates itself as a trigger operation rather than a query operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to poll get_pages_index for progress and final statistics, providing a clear follow-up workflow. However, it doesn't mention when to avoid this tool or mention prerequisites such as authentication, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches one source or all configured sources in the local multilingual trigram index. Use sourceId all for cross-site search; each result includes its actual sourceId for fetch_indexed_section.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| locale | No | all | |
| sourceId | Yes | ||
| urlContains | No | ||
| maxSnippetChars | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It reveals that the search is against a local multilingual trigram index and that each result includes its sourceId, but it doesn't state whether the operation is read-only, whether authentication is required, or any other side effects. This leaves the safety profile largely uncovered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, immediately states the action, and includes a useful usage hint. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no annotations, and no output schema, the description is too sparse. It does not explain the return results beyond sourceId, nor filter semantics or limits, making it incomplete for confident usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description only adds meaningful detail for sourceId (the special 'all' value). Other parameters (query, limit, locale, urlContains, maxSnippetChars) lack any descriptive context beyond schema constraints, leaving the user to infer their purpose from names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a search operation over a multilingual trigram index, specifying single-source or all-sources behavior via sourceId=all, and distinguishes search from sibling tools like fetch_indexed_section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides specific usage guidance ('Use sourceId all for cross-site search') and directs users to fetch_indexed_section with the returned sourceId. However, it doesn't explicitly state when not to use this tool or mention alternative search-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validates a completed interactive authentication session against the configured protected Pages URL and persists only the resulting status.
| Name | Required | Description | Default |
|---|---|---|---|
| sourceId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for disclosing side effects. It does reveal that the tool 'persists only the resulting status', which indicates a write operation. However, it does not mention failure behavior, security requirements, or whether existing status is overwritten. This is partial transparency but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the primary action and result. Every word contributes meaning, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only one parameter and no output schema, the description leaves significant gaps: sourceId is unexplained, the return value is not described, and prerequisites (e.g., completing an interactive session) are implied but not detailed. Sibling tools suggest a broader workflow, but this description does not situate the tool within it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required parameter, sourceId, with no description, and schema description coverage is 0%. The tool description does not mention sourceId or explain its meaning. The parameter semantics are entirely undefined, leaving the agent to guess that sourceId identifies the source, but without any confirmation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's main action: validating a completed interactive authentication session and persisting the resulting status. The verb 'validates' and resource 'completed interactive authentication session' are specific, and it distinguishes itself from siblings like get_source_auth_status (which likely only retrieves status) by emphasizing it persists the status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives. The phrase 'completed interactive authentication session' implies it should follow an interactive auth flow, but no sibling tool is referenced (e.g., begin_source_reauth) and no exclusion criteria are provided. The context is implied, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0begin_source_reauthconfigure_pages_sourcefetch_indexed_sectionfetch_pages_contentget_pages_indexget_source_auth_statuslist_pages_sourcesrefresh_pages_indexsearch_pages_indexvalidate_source_authScored across 10 tools
Most tools have clearly distinct purposes, but some overlap exists between fetch_pages_content and fetch_indexed_section (both retrieve content, one live and one cached), and the three auth-related tools (begin_source_reauth, validate_source_auth, get_source_auth_status) represent sequential steps that could be confused. Descriptions are clear enough to resolve most ambiguity.
All tool names follow a consistent verb_noun snake_case pattern (e.g., begin_source_reauth, fetch_pages_content, list_pages_sources). No casing or naming style deviations are present.
The 10 tools are well-scoped for the server's purpose of retrieving and indexing GitHub Pages content. Each tool covers a distinct step in the configuration, authentication, fetching, and search workflow without unnecessary bloat.
The tool surface covers the core lifecycle: configure, list, authenticate, fetch live content, build and query an index, and retrieve indexed sections. Minor gaps exist, such as no tool to delete or update a configured source, but these do not significantly hinder the primary use case.
Web search and page-reading for AI agents. One-click OAuth connect, or a Caesar API key.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Shared knowledge base for AI agents. Semantic search across agents, no setup required — just a URL.
A cited wiki of your GitHub repo: search, read pages, find symbols and ask, with line citations.
