Skip to main content
Glama
Dthen

iFixit MCP Server

by Dthen
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

iFixit MCP Server

Full-coverage iFixit MCP server — repair guides, device info, repairability scores, categories, search, media, and contributor profiles in one server.

⚠️ LICENSE — READ FIRST

Two licenses apply — do not confuse them:

  1. The code in this repository is licensed under the 0-Clause BSD License (0BSD) — free to use, copy, modify, and distribute for any purpose, including commercial use.

  2. The data the server surfaces comes from the iFixit API and remains iFixit content under a non-commercial CC BY-NC-SA license. Commercial use of iFixit data requires contacting api@ifixit.com for pricing, and per iFixit's Terms of Service: "Training Large Language Models on iFixit content is prohibited."

This server is a read-only, on-demand lookup tool — like a search engine returning snippets, not bulk ingestion for training. It deliberately:

  • Never bulk-downloads or persistently caches the guide corpus. Every request fetches on demand; the in-memory cache is bounded (256 entries) and mirrors iFixit's own CDN TTL (30 min).

  • Has no LLM-training features — no dataset export, no bulk endpoints, no scraping modes.

  • Attributes iFixit in the server description and every tool description (CC BY-NC-SA).

Your 0BSD rights cover the code only, not iFixit's content: keep your use of iFixit data non-commercial, and contact iFixit first if your use case is commercial or involves training.

Why this server?

Research found no existing iFixit MCP servers (see RESEARCH.md §8); this is the first server to cover the full public read surface of the iFixit API 2.0:

  • Search across guides, wikis, questions, products (/suggest)

  • Repair guides — summary or full detail, with steps, parts, and tools

  • Device wiki pages — repairability scores (when iFixit has published one), featured guides, parts/tools counts

  • Category tree — ~16 top-level categories down to nested sub-devices

  • Maintenance schedules — battery/SSD health triggers and other upkeep tasks

  • Media CDN URLs — images, videos, documents by id

  • Contributor profiles — reputation, badges, and guide lists

  • 8 tools, all anonymous and read-only — zero configuration, no API keys, no tokens

Related MCP server: OSF CLI Go

Quick start

cd /home/kimbo/projects/ifixit-mcp
# Any Python 3.10+ venv works; this example uses the Hermes agent venv
/mnt/HC_Volume_105667182/kimbo/.hermes/hermes-agent/venv/bin/python3 -m pip install -e '.[dev]'

Run the server (stdio):

ifixit-mcp                                  # console script
# or
python -m ifixit_mcp.server                 # module entry point

Configuration

Hermes Agent

Add to your Hermes config.yaml:

mcp_servers:
  ifixit:
    command: /mnt/HC_Volume_105667182/kimbo/.hermes/hermes-agent/venv/bin/python3
    args: ['-m', 'ifixit_mcp.server']
    env:
      PYTHONPATH: /home/kimbo/projects/ifixit-mcp/src

Claude Desktop

Add to claude_desktop_config.json — no npx, no Node.js: this is a pure-Python stdio server:

{
  "mcpServers": {
    "ifixit": {
      "command": "/mnt/HC_Volume_105667182/kimbo/.hermes/hermes-agent/venv/bin/python3",
      "args": ["-m", "ifixit_mcp.server"],
      "env": {"PYTHONPATH": "/home/kimbo/projects/ifixit-mcp/src"}
    }
  }
}

Any Python 3.10+ interpreter works in place of the Hermes venv path, as long as the package is installed (or PYTHONPATH points at src/). No environment variables, API keys, or tokens are required for any tool.

Tool reference

All tools are read-only and anonymous. Errors are raised and delivered to the MCP client as error results with isError: true — never returned as success strings and never as stack traces. The wire message is Error executing tool <name>: <family prefix>: <reason> (e.g. Error executing tool get_guide: Guide lookup failed: Guide not found: 1220).

Tool

Params

Returns

search_guides

query, device?, doctypes="guide", lang?

{query, results} — up to 10 search results; guide results compacted to {guideid, title, url, type, difficulty, summary} with summary truncated to 200 chars; other types (wiki, question, product) passed through. lang (e.g. "de") requests localized results. Never cached.

get_guide

guideid, detail="summary", max_steps?, lang?

Guide metadata, parts/tools lists, and step titles only (summary, default) or the full guide (full). In both modes *_rendered HTML is converted to plain text and renamed *_text (step lines: text); summary steps with empty titles fall back to the first line's text (teardown guides often have blank titles); max_steps truncates the steps list in full mode. lang (e.g. "de") requests a localized guide. Cached 30 min.

browse_categories

path?

~16 top-level category names (no path), or the child category names of a subtree (e.g. "Mac/Mac Laptop"); an empty path means top level. Only names are returned — the raw ~1.5 MB tree never leaves the client. Cached 30 min.

get_device

title

Compact device overview: title, display_title, repairability_score (included only when iFixit has published one — it is null/absent for many devices), summary (first 500 chars), featured_guides (title/guideid/url), children (names only), parts_count (list length or, for the live object shape {url, categories:[{tag,count}]}, the sum of the category counts), tools_count, ancestors (breadcrumb names only). Cached 30 min.

list_device_guides

title

The device's guides and featured guides (deduplicated) as a compact list — each entry {guideid, title, url, difficulty, time_required_max, image_thumbnail}, optional fields omitted when absent. Cached 30 min.

get_maintenance_schedule

title

{schedules: [...]} — maintenance tasks and their triggers (e.g. battery_health_percent); {schedules: []} (HTTP 200) when the device has none; inherited_from (parent device name) when the schedule is inherited. Cached 30 min.

get_media

media_id, media_type="images"

The media object with CDN size URLs (mini, thumbnail, standard, original, ...); ungenerated sizes are absent. media_type ∈ images/videos/documents. Cached 1 hour.

get_user

user_id, include_guides=False, limit=20

Contributor profile (username, reputation, join_date, badge_counts, ...); with include_guides=True, merges the user's guides projected to {guideid, title, url} (up to limit guides, 1-200). Cached 30 min.

Response-size management

iFixit's raw API responses are far too large for LLM context budgets, so every tool compacts what it returns:

Raw API payload

Size

What the server returns

Full guide (/guides/{id})

~25 KB small guides, 100 KB+ for large ones (prerequisite steps inlined, full HTML, comments, flags)

summary mode: metadata + parts/tools + step titles only (empty titles fall back to the first line's text); full mode: *_raw markup stripped, *_rendered HTML converted to plain text and renamed *_text (step lines: text), max_steps truncation

Category tree (/categories)

~1.5 MB nested object

Projected name lists only — top-level names or one subtree's children; the tree itself never leaves the client

Device wiki page (/wikis/CATEGORY/{title})

~238 KB, 39 keys

9-field projection: repairability score, 500-char summary, featured-guide stubs, child names, parts/tools counts, ancestors

Search results (/suggest/{q})

Mixed guide/wiki/question objects

Guide results projected to 6 fields with summary truncated to 200 chars at the tool layer; other types already small, passed through

Beyond projection, the client keeps memory bounded:

  • Bounded TTL cache — 256-entry in-memory cache, oldest entries evicted first. TTLs mirror iFixit's CDN edge TTL (observed x-debug-ttl: 1800): 30 min for guides/devices/categories/schedules/users, 1 hour for media. Entries are deep-copied on read and write so callers can never corrupt cached data (category-tree navigation reads the cached tree without copying — it is strictly read-only).

  • Cache stampede protection — concurrent identical requests share one in-flight upstream call; a failed fetch clears its marker so retries work.

  • Volatile endpoints never cached — search (/suggest) and paginated lists (/guides, /users/{id}/guides) bypass the cache entirely.

  • No bulk access — there is no tool that enumerates the corpus; every tool is a targeted, on-demand lookup.

Development

Test-driven workflow: client behavior → server tool wiring → end-to-end tool tests.

# Install with dev dependencies
pip install -e '.[dev]'

# Run the full suite (542 tests)
pytest tests/ -v

Project layout:

ifixit-mcp/
├── src/ifixit_mcp/
│   ├── __init__.py
│   ├── client.py      # IfixitClient — async httpx client, all API logic
│   ├── launcher.py    # stdlib-only entry point: installs startup signal
│   │                  #   handlers before importing mcp, then delegates to
│   │                  #   server.main()
│   └── server.py      # FastMCP tool definitions (thin wrappers + projections)
├── tests/
│   ├── conftest.py
│   ├── test_client.py
│   ├── test_server.py
│   └── test_tools.py
├── RESEARCH.md        # API research findings (live-tested with curl)
├── openapi.json       # Official iFixit API 2.0 OpenAPI 3.1 spec (1.16 MB)
└── pyproject.toml

Architecture

LLM / MCP client
      │  (JSON-RPC over stdio)
      ▼
launcher.py ── stdlib-only console-script entry (ifixit-mcp command)
      │        • installs startup signal handlers BEFORE importing mcp
      │        • delegates to server.main()
      ▼
server.py  ── 8 × @mcp.tool() async wrappers
      │        • input validation, response projection
      │        • every exception → raised error (isError: true on the
      │          wire, message "<prefix>: <reason>", never a traceback)
      │        • lazy shared client (created on first tool call, closed at exit)
      ▼
client.py  ── IfixitClient (async httpx → https://www.ifixit.com/api/2.0)
              • descriptive User-Agent on every request (no fabricated URL)
              • bounded in-memory TTL cache (256 entries, deep-copied)
              • concurrency-safe rate limiter (0.5 s minimum interval, locked)
              • cache stampede dedup (one upstream call per concurrent key)
              • 429 retry with exponential backoff (honors Retry-After, capped at 8s, ≤3 retries)
              • error mapping: 400/401 → ValueError, 403 → ForbiddenError,
                404 → NotFoundError (both ValueError subclasses)
              • response compaction: _summarize_guide, _full_guide,
                _project_device, _compact_guide_item, _html_to_text

  • launcher.py — the stdlib-only console-script entry (backing the ifixit-mcp command): installs startup signal handlers before the heavy mcp import, then delegates to server.main() (which re-installs the full close-client handler before serving). Import-footgun: importing ifixit_mcp.launcher (rather than running the ifixit-mcp command) installs process-wide SIGTERM/SIGINT handlers (os._exit(0)) as an import-time side effect, with no __main__ guard — library consumers embedding ifixit-mcp should import ifixit_mcp.server instead.

  • Startup signals: a SIGTERM/SIGINT in the first ~100ms of interpreter bootstrap (before the module-top handler install runs) may hit the default disposition (exit -15); signals after startup are handled cleanly (exit 0, client closed).

  • client.py — IfixitClient owns all HTTP, caching, rate limiting, retry, and response compaction. Every method validates its inputs before any network I/O, and translates 404s into per-resource messages (Guide not found: 1220, Device not found: iPhone, ...).

  • server.py — a FastMCP server (ifixit) with 8 thin async tools. Each tool delegates to the client, applies the final compact projection (e.g. the 200-char search summary truncation), and converts every exception into a raised error (Error executing tool <name>: <prefix>: <reason> on the wire, isError: true). The server's instructions and every tool description carry the iFixit data attribution (CC BY-NC-SA).

Known limitations

  • Every tool parameter is string-typed with explicit coercion: JSON numbers are coerced to strings and then validated (get_guide with guideid: 1220 works; search_guides with query: 0 searches for "0"); JSON booleans and junk types are rejected, and nulls are rejected for required params (omitted for optional ones) — all with clean family messages, never silent true → 1 fetches, searches for the literal "None", or raw pydantic dumps. The one residual library-level leak: FastMCP (mcp 1.26) exposes no validation-error hook, so a missing required parameter (e.g. calling search_guides with no arguments at all) still surfaces as FastMCP's own [type=missing] pydantic dump — there is no hook to intercept it. Everything the client or tool body can see is converted to a clean message.

License

This project has a dual license structure — the code and the data it serves are licensed separately:

  • Code — the software in this repository is licensed under the 0-Clause BSD License (0BSD): free to use, copy, modify, and distribute for any purpose, with or without fee (SPDX: 0BSD). https://opensource.org/license/0bsd · the full text is in LICENSE.

  • Data — the iFixit content surfaced through this server (guides, wiki pages, media, and other API responses) remains iFixit's content under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) license: non-commercial use only, attribution required, and LLM training on iFixit content is prohibited per iFixit's Terms of Service. https://creativecommons.org/licenses/by-nc-sa/4.0/

The 0BSD grant covers the code only. This server is a read-only, on-demand lookup tool — it never bulk-caches the guide corpus, and nothing in the code license authorizes bulk-ingesting or training on iFixit content.

Links

  • RESEARCH.md — full API research: endpoint inventory, verified response shapes, licensing analysis (§0)

  • openapi.json — official iFixit API 2.0 OpenAPI 3.1 spec (56 paths, 53 schemas)

  • iFixit API docs — official API documentation and licensing terms

Available Tools

8 tools
browse_categoriesA

Browse iFixit's device category tree.

With no path, returns the ~16 top-level category names (e.g. Mac, Phone, Game Console). With a path ("Mac" or "Mac/Mac Laptop"), navigates the nested tree and returns that subtree's child category names. A leaf or empty subtree yields an empty list. Only category names are returned — the raw tree is ~1.5MB and never leaves the client.

Args: path: Optional slash-separated category path to descend into (e.g. "Mac" or "Mac/Mac Laptop"); an empty string means the top level.

Note: Data from iFixit (CC BY-NC-SA). Non-commercial use only.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that only category names are returned (not the full 1.5MB raw tree), that a leaf or empty subtree yields an empty list, and that data is licensed CC BY-NC-SA (non-commercial). It doesn't explicitly state whether invalid paths cause errors, but the overall behavior is well specified. This is solid but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured, starting with a one-sentence purpose, then behavior details, arg explanation, and a licensing note. Every sentence adds value, with no fluff. The format is easy to scan and front-loaded with the most important information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter browsing tool, the description covers all essential context: top-level behavior, nested path behavior, leaf behavior, return format (names only), and data licensing. The presence of an output schema likely covers return structure, so the description doesn't need to explain it. This is complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must fully compensate for the single 'path' parameter. It does: it explains that path is optional, slash-separated, gives examples ('Mac' or 'Mac/Mac Laptop'), and clarifies that an empty string means the top level. This is exemplary parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific verb+resource: 'Browse iFixit's device category tree.' It clearly distinguishes itself from sibling tools (which handle guides, devices, users) by focusing on category navigation. The behavior with and without a path is explained, making the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use the tool: use it with no path for top-level categories, or with a slash-separated path to descend into the tree. It doesn't explicitly name alternatives or exclusions, but the context of sibling tools makes the usage scenario obvious. It falls just short of a 5 because it doesn't explicitly say 'for guides use list_device_guides' or similar.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_deviceA

Get a compact overview of a device wiki page.

Returns {title, display_title, repairability_score (when iFixit has published one), summary (first 500 chars), featured_guides (title/guideid/url only), children (names only), parts_count, tools_count, ancestors (breadcrumb names)}. The raw wiki page can be ~238KB; this projection keeps the response small for context budgets.

Args: title: The device title (e.g. "iPhone").

Note: Data from iFixit (CC BY-NC-SA). Non-commercial use only.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description fully discloses the output structure, including specific field truncations (summary first 500 chars, children names only), and explains the rationale (raw page ~238KB). It also adds usage constraints via licensing and non-commercial use. It lacks explicit error behavior or rate limits, but is comprehensive for core behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and dense: a one-sentence purpose, a concise return-field list, a size rationale, a parameter definition, and a license note. Every sentence adds value with no filler, and the key purpose is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, read-only overview tool, this description covers purpose, output details, and a crucial usage caveat (non-commercial license). It does not mention sibling-specific alternatives or error cases, but the richness of return details makes it sufficiently complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameter descriptions and coverage is 0%, so the description must compensate. It does so by defining 'title' as 'device title' and providing an example ('iPhone'), adding meaning that the schema lacks. This exceeds baseline for undocumented parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Get a compact overview of a device wiki page,' using a specific verb and resource. It clearly distinguishes this tool from siblings like get_guide by emphasizing the compact projection and listing exact return fields, making its purpose clear and non-redundant.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use cases through 'compact overview' and mentions keeping responses small for context budgets, giving practical guidance. However, it does not explicitly name alternative tools or state when not to use this tool, missing the full 'when vs alternatives' criterion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_guideA

Fetch a repair guide by id.

With detail="summary" (default) returns the guide's metadata, parts and tools lists, and step titles only — a compact overview (steps with empty titles fall back to the first line's text). With detail="full" returns everything (steps with rendered text converted to plain text). max_steps truncates the steps list; note it only applies when detail="full" — in summary mode the client ignores it, so the combination is accepted but has no effect.

WARNING: detail="full" guides can exceed 250KB of text — prefer detail="summary" or set max_steps for large guides.

Args: guideid: The guide id (e.g. 1220 or "1220"). detail: One of "summary" (default) or "full". max_steps: Maximum number of steps to include when detail="full" (e.g. 10 or "10"). lang: Optional language code (e.g. "de") for a localized guide (maps to the API's langid parameter).

Note: Data from iFixit (CC BY-NC-SA). Non-commercial use only.

ParametersJSON Schema
NameRequiredDescriptionDefault
langNo
detailNosummary
guideidYes
max_stepsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description takes on the full burden of behavioral disclosure. It explains what each detail level returns (metadata, parts, tools, step titles vs. full rendered text), that max_steps is ignored in summary mode, and includes a WARNING about responses exceeding 250KB. It also discloses the iFixit CC BY-NC-SA data license and non-commercial restriction, which is critical context for usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded: a one-sentence purpose, then paragraph explanations, then a labeled Args list. Every sentence adds value — the warnings, the max_steps caveat, and the licensing note are all necessary. It's detailed but not redundant, hitting the right balance for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 4 parameters, one required, and the description covers all of them with examples and caveats. The presence of an output schema handles return value details, so the description doesn't need to list them. It covers edge cases (max_steps ignored in summary, large response sizes) and licensing, making it fully complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description fully compensates. It explains each parameter in the Args block: guideid with an example, detail with its two allowed values and default, max_steps explaining that it only applies to detail='full', and lang with an example and mapping to the API's langid parameter. This is far beyond what the bare schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Fetch a repair guide by id.' This specifies the exact verb (fetch), the resource (repair guide), and the key identifier (id). It clearly distinguishes this from sibling tools like search_guides or list_device_guides, which deal with finding guides rather than retrieving a specific one.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context on when to use the tool (when you have a guide id) and how to choose between detail='summary' and detail='full'. It even advises preferring summary for large guides. However, it does not explicitly name alternatives or state when not to use this tool (e.g., 'use search_guides to find a guide'). This falls just short of the top tier due to the lack of explicit exclusions or alternative references.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_maintenance_scheduleA

Get a device's maintenance schedule.

Returns {"schedules": [...]} where each schedule describes a maintenance task and its trigger (e.g. battery_health_percent). When the device inherits its schedule from a parent device, the dict also carries "inherited_from" (the parent's name). A device with no maintenance schedule yields {"schedules": []} — that is the API's normal "no schedule" signal (HTTP 200), not an error.

Args: title: The device title (e.g. "iPhone").

Note: Data from iFixit (CC BY-NC-SA). Non-commercial use only.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It covers output shape, inheritance semantics, the HTTP 200 empty-schedule signal, and even the licensing restriction (non-commercial use). This is thorough and goes beyond what the schema alone conveys.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded: a one-sentence purpose, then a clear return-value explanation, an Args section, and a licensing note. No sentence is wasted, and all important details are presented compactly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single required parameter, the description is highly complete. It explains the return schema, the inherited_from case, the no-schedule case (HTTP 200, not error), and licensing. The presence of an output schema further reduces the need to document return values, but the description already does so thoroughly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides no description for the 'title' parameter (0% schema coverage). The description compensates by explaining that 'title' is the device title and providing an example ('iPhone'). This adds meaningful semantic information beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description begins with a specific verb+resource construction: 'Get a device's maintenance schedule.' It clearly defines the tool's purpose and differentiates it from sibling tools like get_device or list_device_guides by focusing on maintenance schedule retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: use this tool by supplying a device title to obtain its maintenance schedule. It also explains important edge-case behavior (empty schedules are normal, not errors) and inheritance behavior, giving the agent a solid sense of when and how to invoke it. However, it does not explicitly mention alternatives or when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_mediaA

Resolve a media object's CDN URLs by id.

Returns the API's image/media object with CDN size URLs (mini, thumbnail, standard, original, ...); ungenerated sizes are absent. Media access is permission-checked: assets not referenced by content you can view return an error.

Args: media_id: The media id (e.g. 14056 or "14056"). media_type: One of "images" (default), "videos", or "documents".

Note: Data from iFixit (CC BY-NC-SA). Non-commercial use only.

ParametersJSON Schema
NameRequiredDescriptionDefault
media_idYes
media_typeNoimages

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that ungenerated sizes are absent, that access is permission-checked (errors for unauthorized content), and includes a licensing note. This provides meaningful behavioral context beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, with a clear one-line purpose, a behavior summary, and a labeled Args section. Every sentence adds value, and the licensing note is brief and relevant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 2-parameter tool, the description covers purpose, behavior, permissions, licensing, and parameters. Since an output schema exists, the description doesn't need to detail return values, but it still describes CDN size URLs and absent sizes, making it complete for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 media_id with an example (14056 or '14056'), enumerates media_type values ('images', 'videos', 'documents'), and notes the default 'images'. This adds practical guidance beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Resolve') and resource ('media object's CDN URLs by id'). It distinguishes from sibling tools (guides, devices, users) by focusing on media retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for resolving media URLs but does not explicitly state when to use this tool over alternatives or exclude other tools. No reference to sibling tools or alternative approaches is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_userA

Fetch an iFixit contributor profile.

Returns the user's profile dict (username, reputation, join_date, badge_counts, ...). With include_guides=True, merges the profile with the user's guide list into {"user": ..., "guides": [...]} where each guide is projected to {guideid, title, url}.

include_guides is all-or-nothing: if either the profile fetch or the guide-list fetch fails (ValueError, network error, or malformed response), the whole call raises a single clean error — partial data is never returned.

Args: user_id: The user id (e.g. 1 or "1"). include_guides: When True, also fetch and include the user's guides (projected to guideid/title/url). Accepts true/false (also as JSON booleans) or 1/0; any other value is rejected with a clean error. limit: Maximum number of guides to include when include_guides=True (1-200, default 20; e.g. 5 or "5"). The API clamps at 200. Validated unconditionally — junk is rejected even when include_guides=False leaves it unused (QA Round 12, F12-7).

Note: Data from iFixit (CC BY-NC-SA). Non-commercial use only.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo20
user_idYes
include_guidesNofalse

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavior: it specifies the return dict, the all-or-nothing failure mode that never returns partial data, unconditional validation of limit (even when unused), and API clamping at 200. This goes well beyond a basic fetch, describing error semantics and edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with an Args section and front-loaded purpose, but it is somewhat long and includes a QA reference (F12-7) that is irrelevant to callers. Overall it's well-organized and each sentence earns its place, but slight over-elaboration keeps it from a top score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (conditional merging, validation quirks) and lack of annotations, the description covers all necessary behavior: return shape, errors, licensing, and parameter constraints. Output schema exists, so full return expansion is unnecessary; the description is complete for invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description compensates by documenting each parameter in detail: user_id accepts strings or ints, include_guides accepts booleans/1/0 with clean rejection, and limit has range, default, clamping, and unconditional validation notes. This provides essential meaning the schema omits.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the core purpose with a specific verb ('Fetch') and resource ('iFixit contributor profile'), differentiating it from sibling guide/device tools. It also clarifies the optional guide-merge behavior, further scoping the functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly name alternatives or state when to use this tool versus siblings like get_guide. Usage is implied by the 'Fetch a profile' verb, but there are no exclusions or alternative recommendations, so this is a gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_device_guidesA

List the repair guides available for a device.

Returns the device's guides (and featured guides) as a compact list — each entry is projected to {guideid, title, url, difficulty, time_required_max, image_thumbnail}, with optional fields omitted when the API did not provide them.

Args: title: The device title (e.g. "iPhone").

Note: Data from iFixit (CC BY-NC-SA). Non-commercial use only.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden. It discloses the projective output, that optional fields are omitted when unavailable, and adds a licensing/usage restriction (CC BY-NC-SA, non-commercial). It does not cover error handling or pagination, but it goes beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the main action, then organizes return format, args, and license note in a logical, compact structure. Every sentence contributes value, and there is no irrelevant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter list tool, the description covers the essential elements: action, input, output shape, and legal usage. The output schema likely documents return fields, so further detail isn't necessary. Edge cases like empty results or invalid title are not addressed, but they are minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 explains the single title parameter with a concrete example ('iPhone'), which is helpful. It stops short of specifying matching rules (exact vs partial) or case sensitivity, but it is clear enough for basic use.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear, specific verb-resource statement: 'List the repair guides available for a device.' This distinguishes it from siblings like get_guide (retrieving a single guide) and search_guides (query-based search), and it also names the return fields, leaving no ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by specifying that it works 'for a device' and requires a title, but it never explicitly states when to choose this over search_guides or get_guide, nor does it mention exclusions. The guidance is implied, not overt.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_guidesA

Search iFixit's catalog for repair guides (and other content types).

Returns up to 10 results as {"query": ..., "results": [...]}. Guide results are compacted to {guideid, title, url, type, difficulty, summary} with summary truncated to 200 characters; other result types (wiki, question, product) pass through as returned by the API. Use the device parameter to scope results to a specific device (e.g. "iPhone 13"). Search results are volatile and never cached.

Args: query: Free-text search query (e.g. "battery replacement"). device: Restrict results to a single device by name (maps to the API's guideDevice parameter). doctypes: Comma-separated result types: guide, item, topic, device, category, question, post, or all (default "guide"). lang: Optional language code (e.g. "de") for localized results (maps to the API's langid parameter).

Note: Data from iFixit (CC BY-NC-SA). Non-commercial use only.

ParametersJSON Schema
NameRequiredDescriptionDefault
langNo
queryYes
deviceNo
doctypesNoguide

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so thoroughly. It discloses result limits (up to 10), result compaction for guides, pass-through for other types, volatility of results ('never cached'), parameter mapping to API fields, and licensing restrictions (CC BY-NC-SA). This exceeds typical descriptions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized and front-loaded: it starts with purpose, then return format, then usage, then parameter details, and ends with licensing. Every sentence adds value without redundancy. The structure—a brief overview followed by a bullet-like Args list—is easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (4 params, multiple result types, API mappings), the description covers all necessary context: query syntax, result structure, limits, volatility, and licensing. An output schema exists but the description already provides return value details, so the context is fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description's Args section fully compensates by explaining every parameter with types, examples, defaults, and API mappings. For instance, it clarifies that 'device' maps to guideDevice, 'lang' to langid, and doctypes accepts a specific value list. This is highly informative.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Search' and the resource 'iFixit's catalog for repair guides (and other content types)'. It distinguishes itself from siblings by specifying it returns multiple result types and mentions the device parameter for scoping, which separates it from list_device_guides and get_guide.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: how to use the device parameter to scope results, how doctypes restrict result types, and the lang parameter for localization. It lacks explicit exclusions or alternatives (e.g., 'for a specific device use list_device_guides'), but the guidance is sufficient for an agent to decide when to invoke it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 8 tool updatesv0.1.0
    • First observedbrowse_categories
    • First observedget_device
    • First observedget_guide
    • First observedget_maintenance_schedule
    • First observedget_media
    • First observedget_user
    • First observedlist_device_guides
    • First observedsearch_guides
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.6/5.0
Disambiguation5/5

Each tool targets a distinct resource or action: guides, maintenance schedules, media, users, search, categories, and devices. There is no meaningful overlap—list_device_guides and get_guide differ by granularity, and browse_categories complements get_device rather than duplicating it.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case: get_ for fetching specific entities, list_/search_/browse_ for discovery. This is uniform and predictable.

Tool Count5/5

Eight tools is well within the ideal 3–15 range and covers the read-only iFixit domain without bloat. Each tool earns its place, and the count is appropriate for the server's stated purpose.

Completeness5/5

The surface covers the core workflows: discovering devices, browsing categories, listing and fetching guides, searching, retrieving maintenance schedules, user profiles, and media assets. As a read-only server, there are no obvious lifecycle gaps—the only missing operations (create/update/delete) are not part of the domain.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • OSF CLI Go

    edithatogo
    A
    license
    A
    quality
    A
    maintenance
    Read-only MCP tools for authenticated Open Science Framework projects, components, files, and contributors.
    6
    1
    Apache 2.0

  • osrs-wiki-mcp

    SSanderV
    A
    license
    A
    quality
    A
    maintenance
    Provides read-only access to Old School RuneScape Wiki data, returning structured content with source provenance via MCP tools for searching pages, items, monsters, quests, shops, and drop sources.
    10
    28
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Dthen/ifixit-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server