ionic-framework-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ionic Framework MCP Server

Ionic Framework MCP 服务器

Connect an MCP client to the hosted Ionic Framework MCP server for the current Ionic Framework documentation, the component API reference, the official usage examples per framework, and the Ionic blog.

The server is hosted by Capawesome — there is nothing to install, no account, and no token:

https://ionic-framework-mcp.capawesome.io/mcp

This is an unofficial server. It is maintained by Capawesome and is not affiliated with or endorsed by Ionic or OutSystems. It serves the official Ionic Framework documentation, © the Ionic team and licensed under Apache-2.0.

将 MCP 客户端连接到托管的 Ionic Framework MCP 服务器，以获取当前的 Ionic Framework 文档、组件 API 参考、各框架的官方用法示例和 Ionic 博客。

该服务器由 Capawesome 托管——无需安装任何内容，也不需要账户或 token：

https://ionic-framework-mcp.capawesome.io/mcp

这是一个非官方服务器，由 Capawesome 维护，与 Ionic 或 OutSystems 无隶属关系，也未获得其认可。它提供官方 Ionic Framework 文档，版权归 Ionic 团队所有，并依据 Apache-2.0 授权。

Prerequisites

前提条件

An MCP client: Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed, or any other client that implements the Model Context Protocol.

Network access to

https://ionic-framework-mcp.capawesome.io

For clients that only start local commands: Node.js 22 or later.

一个 MCP 客户端：Claude Code、Claude Desktop、Cursor、VS Code、Windsurf、Zed，或任何其他实现了 Model Context Protocol 的客户端。

能够访问

https://ionic-framework-mcp.capawesome.io

的网络连接。

对于只能启动本地命令的客户端：Node.js 22 或更高版本。

Agent Behavior

Agent 行为

Guide step-by-step. Walk the user through the process one step at a time. Never present multiple unrelated questions at once.
Auto-detect before asking. Detect the MCP client from the project before asking the user which one they use.
Never ask for credentials. The server needs no account and no token. Never prompt for one and never write an
```
Authorization
```
header into the configuration.
Pass the matching documentation version and framework. Read the Ionic package from
```
package.json
```
and pass the matching
```
version
```
on every call, and the project's
```
framework
```
when reading usage examples. See Documentation Versions.

逐步指导。 每次只引导用户完成流程中的一个步骤。切勿一次提出多个互不相关的问题。
提问前先自动检测。 在询问用户使用哪个客户端之前，先从项目中检测 MCP 客户端。
绝不索要凭据。 该服务器不需要账户或 token。绝不提示用户提供，也绝不将
```
Authorization
```
请求头写入配置。
传入匹配的文档版本和框架。 从
```
package.json
```
中读取 Ionic 包版本，并在每次调用时传入匹配的
```
version
```
；读取用法示例时传入项目的
```
framework
```
。参见文档版本。

Procedures

操作步骤

Step 1: Detect the MCP Client

第 1 步：检测 MCP 客户端

Detect the client instead of asking, by checking the project root in this order:

```
.mcp.json
```
or
```
.claude/
```
→ Claude Code
```
.cursor/mcp.json
```
or
```
.cursor/
```
→ Cursor
```
.vscode/mcp.json
```
or
```
.vscode/
```
→ VS Code

If none of these exist, or if more than one matches, ask the user which client to configure. Claude Desktop, Windsurf, and Zed keep their configuration outside the project, so they cannot be detected this way.

不要直接询问用户，而应按以下顺序检查项目根目录来检测客户端：

```
.mcp.json
```
或
```
.claude/
```
→ Claude Code
```
.cursor/mcp.json
```
或
```
.cursor/
```
→ Cursor
```
.vscode/mcp.json
```
或
```
.vscode/
```
→ VS Code

如果这些文件都不存在，或匹配到多个客户端，则询问用户要配置哪个客户端。Claude Desktop、Windsurf 和 Zed 将配置保存在项目之外，因此无法通过这种方式检测。

Step 2: Add the Server

第 2 步：添加服务器

Read

references/client-setup.md

and apply the section for the detected client. Register the server under the name

ionic-framework

读取

references/client-setup.md

，并应用检测到的客户端对应的章节。以名称

ionic-framework

注册该服务器。

Step 3: Restart the Client and Verify

第 3 步：重启客户端并验证

Tell the user to restart their MCP client so it picks up the new server.
Verify the server by asking the client to run
```
list_components
```
with a query such as
```
modal
```
.
If the call fails, go to Error Handling.

告知用户重启 MCP 客户端，使其加载新服务器。
让客户端使用诸如
```
modal
```
这样的查询调用
```
list_components
```
，以验证服务器。
如果调用失败，请转到错误处理。

Step 4: Use the Server

第 4 步：使用服务器

Once connected, prefer these tools over model knowledge and over reference files bundled with other skills whenever the topic is the Ionic Framework — a component, its API, theming, navigation, or the Ionic CLI.

Tool	Parameters	Use for
`search_docs`	`query` (required), `section` , `version` , `limit`	Finding the page that covers a topic. Start here.
`get_doc_page`	`url` (required), `version`	Reading a full page as Markdown, using a URL from `search_docs` or `list_components` .
`list_components`	`query` , `version` , `limit`	Finding the component that fits a piece of UI, and the tag it is used under.
`get_component_usage`	`component` (required), `example` , `framework` , `version`	Reading the official usage examples of a component.
`list_blog_posts`	—	Recent posts from the Ionic blog, for announcements and release notes.

Apply these rules:

Read the component page before styling or wiring a component. A component page returned by
```
get_doc_page
```
carries the full API reference — properties, events, methods, CSS shadow parts, CSS custom properties, and slots. Reading it is what prevents an invented property or class name.
Call
get_component_usage
without an
example
first to list the examples a component offers, then call it again with the chosen
```
example
```
id.
Pass
framework
as
```
angular
```
,
```
react
```
,
```
vue
```
, or
```
javascript
```
to get the variant that matches the project. Without it, every framework is returned.
Narrow with
section
when the question belongs to one part of the documentation:
```
components
```
,
```
angular
```
,
```
react
```
,
```
vue
```
,
```
theming
```
,
```
guides
```
,
```
updating
```
, or
```
cli
```
.
Pass
limit
up to 100 to
```
list_components
```
to list every component.
Route other topics elsewhere. Capacitor, its plugins, and the native iOS and Android projects belong to the Capacitor MCP server; Capawesome plugins and Capawesome Cloud belong to the Capawesome MCP server. See Related Skills.

连接成功后，当主题涉及 Ionic Framework（组件、API、主题、导航或 Ionic CLI）时，优先使用这些工具，而不是模型自身知识，也优先于其他 skill 附带的参考文件。

工具	参数	适用于
`search_docs`	`query` （必填）、 `section` 、 `version` 、 `limit`	查找涵盖某主题的页面。始于此处。
`get_doc_page`	`url` （必填）、 `version`	使用 `search_docs` 或 `list_components` 返回的 URL，以 Markdown 格式读取完整页面。
`list_components`	`query` 、 `version` 、 `limit`	查找适合某个 UI 场景的组件及其所属标签。
`get_component_usage`	`component` （必填）、 `example` 、 `framework` 、 `version`	读取组件的官方用法示例。
`list_blog_posts`	—	Ionic 博客的近期文章，用于公告和发布说明。

应用以下规则：

设置组件样式或连接组件逻辑前，先阅读组件页面。 由
```
get_doc_page
```
返回的组件页面包含完整的 API 参考——属性、事件、方法、CSS shadow parts、CSS 自定义属性和 slots。阅读该页面可避免凭空使用不存在的属性名或类名。
先调用不带
example
的
get_component_usage
，列出组件提供的示例，然后使用选定的
```
example
```
id 再次调用。
将
framework
传为
```
angular
```
、
```
react
```
、
```
vue
```
或
```
javascript
```
，以获取与项目匹配的变体。如果不传，则会返回所有框架的示例。
当问题属于文档的某个部分时，使用
section
缩小范围：
```
components
```
、
```
angular
```
、
```
react
```
、
```
vue
```
、
```
theming
```
、
```
guides
```
、
```
updating
```
或
```
cli
```
。
将
limit
传给
list_components
，最高可设为 100，以列出所有组件。
将其他主题分流至相应服务器。 Capacitor、其插件以及原生 iOS 和 Android 项目应使用 Capacitor MCP 服务器；Capawesome 插件和 Capawesome Cloud 应使用 Capawesome MCP 服务器。参见相关 Skill。

Documentation Versions

文档版本

The documentation is available for v9 (the default) and v8.

Read the version of

@ionic/core

@ionic/angular

@ionic/react

, or

@ionic/vue

from

package.json

and map it:

Ionic package	`version`
`9.x`	`v9`
`8.x`	`v8`

Pass it on every

search_docs

get_doc_page

list_components

, and

get_component_usage

call. Without it the server answers for v9, which documents properties and events an older release does not have.

The same

package.json

entry gives the

framework

for

get_component_usage

@ionic/angular

→

angular

@ionic/react

→

react

@ionic/vue

→

vue

, and

@ionic/core

on its own →

javascript

文档提供 v9（默认版本）和 v8 两个版本。

从

package.json

中读取

@ionic/core

、

@ionic/angular

、

@ionic/react

或

@ionic/vue

的版本，并映射如下：

Ionic 包	`version`
`9.x`	`v9`
`8.x`	`v8`

每次调用

search_docs

、

get_doc_page

、

list_components

和

get_component_usage

时都要传入该版本。如果不传，服务器将按 v9 作答，而 v9 包含旧版本没有的属性和事件。

同一个

package.json

条目也提供

get_component_usage

所需的

framework

：

@ionic/angular

→

angular

，

@ionic/react

→

react

，

@ionic/vue

→

vue

，单独使用

@ionic/core

→

javascript

。

Error Handling

错误处理

Server not listed after setup: The client was not restarted. Restart it. In Claude Code, run
```
claude mcp list
```
to confirm the server is registered.
429 Too Many Requests
: The endpoint allows 100 requests per minute per IP. Retry after a short wait.
The client cannot reach a remote server: It only starts local commands. Use the
```
@capawesome/ionic-framework-mcp
```
stdio proxy as shown in
```
references/client-setup.md
```
. It requires Node.js 22 or later.
A component has no description in
list_components
: Some components carry none upstream. Read the component page with
```
get_doc_page
```
instead.
get_component_usage
reports an unknown example: The response lists the available example ids. Call the tool again with one of them.
A tool reports that the index is being built: The server rebuilds its index daily. Retry after a short wait.
Answers mention properties the project does not have: The
```
version
```
parameter was omitted or wrong. See Documentation Versions.

完成设置后未列出服务器：客户端尚未重启。重启客户端。在 Claude Code 中，运行
```
claude mcp list
```
以确认服务器已注册。
429 Too Many Requests
：该端点允许每个 IP 每分钟发送 100 个请求。短暂等待后重试。
客户端无法访问远程服务器：该客户端只能启动本地命令。按照
```
references/client-setup.md
```
中所示，使用
```
@capawesome/ionic-framework-mcp
```
stdio 代理。该代理需要 Node.js 22 或更高版本。
list_components
中的组件没有描述：部分组件在上游没有描述。请改用
```
get_doc_page
```
阅读组件页面。
get_component_usage
报告示例未知：响应中会列出可用的示例 id。使用其中之一再次调用该工具。
工具提示正在构建索引：服务器每天都会重建索引。短暂等待后重试。
回答中提到项目不存在的属性：
```
version
```
参数被省略或设置错误。参见文档版本。