Skip to content

Commit d86b57a

Browse files
tannerlinsleytannerlinsley
committed
mcp
1 parent f58f420 commit d86b57a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

77 files changed

+7817
-1359
lines changed

‎docs/mcp/config.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"$schema": "https://tanstack.com/tanstack-docs-config.schema.json",
3+
"docSearch": {
4+
"appId": "FQ0DQ6MA3C",
5+
"apiKey": "10c34d6a5c89f6048cf644d601e65172",
6+
"indexName": "tanstack-test"
7+
},
8+
"sections": [
9+
{
10+
"label": "Getting Started",
11+
"children": [
12+
{ "label": "Overview", "to": "overview" },
13+
{ "label": "Connecting", "to": "connecting" }
14+
]
15+
},
16+
{
17+
"label": "Reference",
18+
"children": [{ "label": "Available Tools", "to": "tools" }]
19+
}
20+
]
21+
}

‎docs/mcp/connecting.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
id: connecting
3+
title: Connecting
4+
---
5+
6+
The TanStack MCP Server is available at `https://tanstack.com/api/mcp` and uses the Streamable HTTP transport. Authentication via API key is required.
7+
8+
## Getting an API Key
9+
10+
Before connecting, you'll need to create an API key:
11+
12+
1. [Sign in to your TanStack account](/login)
13+
2. Go to [API Keys](/account/api-keys)
14+
3. Click "New Key" and give it a descriptive name
15+
4. Copy the key immediately (you won't see it again)
16+
17+
> [!NOTE]
18+
> Replace `YOUR_API_KEY` in the examples below with your actual API key.
19+
20+
## OpenCode
21+
22+
Add to your OpenCode MCP configuration in `~/.config/opencode/config.json`:
23+
24+
```json
25+
{
26+
"mcp": {
27+
"servers": {
28+
"tanstack": {
29+
"type": "remote",
30+
"url": "https://tanstack.com/api/mcp",
31+
"headers": {
32+
"Authorization": "Bearer YOUR_API_KEY"
33+
}
34+
}
35+
}
36+
}
37+
}
38+
```
39+
40+
## Claude Code
41+
42+
```bash
43+
claude mcp add --transport http tanstack https://tanstack.com/api/mcp --header "Authorization: Bearer YOUR_API_KEY"
44+
```
45+
46+
## Cursor
47+
48+
Add to your Cursor MCP configuration:
49+
50+
```json
51+
{
52+
"mcpServers": {
53+
"tanstack": {
54+
"command": "npx",
55+
"args": ["mcp-remote", "https://tanstack.com/api/mcp"],
56+
"env": {
57+
"MCP_HEADERS": "Authorization: Bearer YOUR_API_KEY"
58+
}
59+
}
60+
}
61+
}
62+
```
63+
64+
## VS Code
65+
66+
Add to your VS Code settings or `.vscode/mcp.json`:
67+
68+
```json
69+
{
70+
"servers": {
71+
"tanstack": {
72+
"type": "http",
73+
"url": "https://tanstack.com/api/mcp",
74+
"headers": {
75+
"Authorization": "Bearer YOUR_API_KEY"
76+
}
77+
}
78+
}
79+
}
80+
```
81+
82+
## Claude Desktop
83+
84+
Add the following to your Claude Desktop configuration file:
85+
86+
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
87+
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
88+
89+
```json
90+
{
91+
"mcpServers": {
92+
"tanstack": {
93+
"command": "npx",
94+
"args": ["mcp-remote", "https://tanstack.com/api/mcp"],
95+
"env": {
96+
"MCP_HEADERS": "Authorization: Bearer YOUR_API_KEY"
97+
}
98+
}
99+
}
100+
}
101+
```
102+
103+
Restart Claude Desktop after updating the configuration.
104+
105+
## Windsurf
106+
107+
Add to your Windsurf MCP configuration:
108+
109+
```json
110+
{
111+
"mcpServers": {
112+
"tanstack": {
113+
"serverUrl": "https://tanstack.com/api/mcp",
114+
"headers": {
115+
"Authorization": "Bearer YOUR_API_KEY"
116+
}
117+
}
118+
}
119+
}
120+
```
121+
122+
## MCP Inspector
123+
124+
Use the MCP Inspector to test the server interactively:
125+
126+
```bash
127+
npx @modelcontextprotocol/inspector https://tanstack.com/api/mcp --header "Authorization: Bearer YOUR_API_KEY"
128+
```
129+
130+
## Custom Integration
131+
132+
For custom integrations, the server accepts standard MCP requests via HTTP:
133+
134+
- **Endpoint:** `https://tanstack.com/api/mcp`
135+
- **Transport:** Streamable HTTP (stateless)
136+
- **Methods:** POST (for requests), GET (for server-sent events), DELETE (for session cleanup)
137+
- **Authentication:** Bearer token via Authorization header
138+
139+
Example request using curl:
140+
141+
```bash
142+
curl -X POST https://tanstack.com/api/mcp \
143+
-H "Content-Type: application/json" \
144+
-H "Authorization: Bearer YOUR_API_KEY" \
145+
-d '{
146+
"jsonrpc": "2.0",
147+
"id": 1,
148+
"method": "tools/list"
149+
}'
150+
```
151+
152+
## Rate Limits
153+
154+
API requests are rate-limited to protect the service:
155+
156+
- **Authenticated requests:** 60 requests per minute
157+
- Rate limit headers are included in responses (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`)
158+
159+
## Verifying Connection
160+
161+
After connecting, ask your AI assistant to list TanStack libraries:
162+
163+
> "Use the TanStack MCP to list all available libraries"
164+
165+
You should see a list of all TanStack libraries with their versions and descriptions.

‎docs/mcp/overview.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
id: overview
3+
title: Overview
4+
---
5+
6+
TanStack MCP Server provides AI assistants with direct access to TanStack documentation through the [Model Context Protocol](https://modelcontextprotocol.io). This allows AI tools like Claude, Cursor, and others to search and retrieve up-to-date documentation for all TanStack libraries.
7+
8+
## Why Use the MCP Server?
9+
10+
AI assistants are trained on snapshots of documentation that become stale over time. The TanStack MCP Server solves this by giving AI tools real-time access to:
11+
12+
- **Current documentation** for all TanStack libraries (Router, Query, Table, Form, Virtual, Store, and more)
13+
- **Version-specific docs** for the exact version you're using
14+
- **Full-text search** across all documentation
15+
16+
## Quick Start
17+
18+
Copy and paste the following instructions to your AI agent:
19+
20+
> [!NOTE]
21+
> Replace `YOUR_API_KEY` with an API key from [tanstack.com/account/api-keys](/account/api-keys)
22+
23+
```
24+
Connect to the TanStack MCP server with these settings:
25+
26+
URL: https://tanstack.com/api/mcp
27+
Transport: Streamable HTTP
28+
Authorization Header: Bearer YOUR_API_KEY
29+
```
30+
31+
See [Connecting](./connecting) for client-specific setup instructions.
32+
33+
## Available Tools
34+
35+
The MCP server exposes three tools:
36+
37+
| Tool | Description |
38+
| ---------------- | ------------------------------------------------------------ |
39+
| `list_libraries` | List all TanStack libraries with their versions and metadata |
40+
| `get_doc` | Fetch a specific documentation page by library and path |
41+
| `search_docs` | Full-text search across all TanStack documentation |
42+
43+
See [Available Tools](./tools) for detailed parameter documentation.
44+
45+
## How It Works
46+
47+
The TanStack MCP Server uses the Streamable HTTP transport, making it compatible with serverless deployments and any MCP client that supports HTTP transport. When your AI assistant needs TanStack documentation, it calls the appropriate tool and receives the content directly.
48+
49+
```
50+
AI Assistant → MCP Client → TanStack MCP Server → Documentation
51+
```
52+
53+
All documentation is fetched directly from the TanStack GitHub repositories, ensuring you always get the most current content for your specified version.

‎docs/mcp/tools.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
id: tools
3+
title: Available Tools
4+
---
5+
6+
The TanStack MCP Server exposes three tools for accessing documentation. Each tool is designed for a specific use case.
7+
8+
## list_libraries
9+
10+
List all available TanStack libraries with their metadata.
11+
12+
### Parameters
13+
14+
| Parameter | Type | Required | Description |
15+
| --------- | ------ | -------- | ------------------------------------------------------------------- |
16+
| `group` | string | No | Filter by group: `state`, `headlessUI`, `performance`, or `tooling` |
17+
18+
### Response
19+
20+
Returns an object containing:
21+
22+
- `group` - The group name or "All Libraries"
23+
- `count` - Number of libraries returned
24+
- `libraries` - Array of library objects with `id`, `name`, `tagline`, `description`, `frameworks`, `latestVersion`, `docsUrl`, and `githubUrl`
25+
26+
### Example
27+
28+
```json
29+
{
30+
"name": "list_libraries",
31+
"arguments": {
32+
"group": "state"
33+
}
34+
}
35+
```
36+
37+
---
38+
39+
## get_doc
40+
41+
Fetch a specific documentation page by library and path.
42+
43+
### Parameters
44+
45+
| Parameter | Type | Required | Description |
46+
| --------- | ------ | -------- | --------------------------------------------------------------------------------------- |
47+
| `library` | string | Yes | Library ID (e.g., `query`, `router`, `table`, `form`) |
48+
| `path` | string | Yes | Documentation path (e.g., `framework/react/overview`, `framework/react/guides/queries`) |
49+
| `version` | string | No | Version (e.g., `v5`, `v1`). Defaults to `latest` |
50+
51+
### Response
52+
53+
Returns an object containing:
54+
55+
- `title` - Document title from frontmatter
56+
- `content` - Full markdown content of the document
57+
- `url` - Canonical URL to the documentation page
58+
- `library` - Library name
59+
- `version` - Resolved version
60+
61+
### Example
62+
63+
```json
64+
{
65+
"name": "get_doc",
66+
"arguments": {
67+
"library": "query",
68+
"path": "framework/react/guides/queries",
69+
"version": "v5"
70+
}
71+
}
72+
```
73+
74+
### Common Documentation Paths
75+
76+
Most TanStack libraries follow this path structure:
77+
78+
- `framework/{framework}/overview` - Framework-specific overview
79+
- `framework/{framework}/installation` - Installation guide
80+
- `framework/{framework}/guides/{topic}` - Guides for specific topics
81+
- `framework/{framework}/reference/{api}` - API reference
82+
83+
Where `{framework}` is one of: `react`, `vue`, `solid`, `svelte`, `angular`
84+
85+
---
86+
87+
## search_docs
88+
89+
Full-text search across all TanStack documentation.
90+
91+
### Parameters
92+
93+
| Parameter | Type | Required | Description |
94+
| ----------- | ------ | -------- | ------------------------------------------------------------ |
95+
| `query` | string | Yes | Search query |
96+
| `library` | string | No | Filter to specific library (e.g., `query`, `router`) |
97+
| `framework` | string | No | Filter to specific framework (e.g., `react`, `vue`, `solid`) |
98+
| `limit` | number | No | Maximum results (default: 10, max: 50) |
99+
100+
### Response
101+
102+
Returns an object containing:
103+
104+
- `query` - The search query
105+
- `totalHits` - Total number of matching documents
106+
- `results` - Array of search results with `title`, `url`, `snippet`, `library`, and `breadcrumb`
107+
108+
### Example
109+
110+
```json
111+
{
112+
"name": "search_docs",
113+
"arguments": {
114+
"query": "useQuery refetch",
115+
"library": "query",
116+
"framework": "react",
117+
"limit": 5
118+
}
119+
}
120+
```
121+
122+
---
123+
124+
## Usage Tips
125+
126+
### Finding Documentation
127+
128+
1. **Start with `list_libraries`** to discover available libraries and their IDs
129+
2. **Use `search_docs`** to find specific topics when you don't know the exact path
130+
3. **Use `get_doc`** to fetch the full content once you know the path
131+
132+
### Version Handling
133+
134+
- Use `latest` (default) to always get the current documentation
135+
- Specify a version like `v5` or `v4` when working with a specific library version
136+
- The `list_libraries` tool shows available versions for each library
137+
138+
### Path Discovery
139+
140+
Search results include URLs that reveal the documentation path structure. For example, a URL like `https://tanstack.com/query/latest/docs/framework/react/guides/queries` indicates:
141+
142+
- Library: `query`
143+
- Path: `framework/react/guides/queries`

0 commit comments

Comments
 (0)