Skip to content

[feat]: add MCP server#131

Open
LadyBluenotes wants to merge 6 commits intomainfrom
mcp
Open

[feat]: add MCP server#131
LadyBluenotes wants to merge 6 commits intomainfrom
mcp

Conversation

@LadyBluenotes
Copy link
Copy Markdown
Member

@LadyBluenotes LadyBluenotes commented May 11, 2026

Summary

Adds a new @tanstack/intent-mcp package that exposes Intent skill discovery/loading through a read-only stdio MCP server.

  • Adds intent_search, intent_load, and intent_status tools
  • Keeps the local skill catalog out of tools/list
  • Loads exact skills into a <skill_content> block
  • Adds compact default responses and process-level skill list caching
  • Keeps MCP SDK dependencies out of the main @tanstack/intent package
  • Adds consumer docs for configuring the MCP server
  • Adds MCP protocol tests using the SDK in-memory transport and checked-in fixtures

Summary by CodeRabbit

  • Documentation

    • Added MCP Server Quick Start guide with client configuration examples and setup instructions.
    • Documented available MCP server tools and read-only server behavior.
  • New Features

    • Released intent-mcp CLI tool enabling agents to search Intent skills, load individual skill details, and monitor server status via MCP protocol.
  • Tests

    • Added comprehensive test suite for MCP server operations.
  • Chores

    • Added test script for intent-mcp package.

Review Change Stack

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 11, 2026

📝 Walkthrough

Walkthrough

This PR introduces @tanstack/intent-mcp, a new package implementing a Model Context Protocol (MCP) server for TanStack Intent skill discovery and loading. It includes a server factory registering three tools (intent_search, intent_load, intent_status), a CLI entry point, comprehensive in-memory transport tests with fixtures, and user documentation with configuration examples.

Changes

MCP Server Implementation

Layer / File(s) Summary
Package Configuration & Build Setup
packages/intent-mcp/package.json, packages/intent-mcp/tsconfig.json, package.json
New @tanstack/intent-mcp ESM package with CLI binary (intent-mcp), runtime dependencies (@modelcontextprotocol/sdk, @tanstack/intent, zod), build scripts (tsdown + type declaration generation), and root-level test:intent-mcp script.
Server Input Schemas & Types
packages/intent-mcp/src/server.ts (lines 1–44)
Zod schemas and TypeScript interfaces for shared tool arguments: repository root resolution, global vs. global-only search flags, package exclusion patterns, and optional debug output.
Caching & Response Utilities
packages/intent-mcp/src/server.ts (lines 45–116)
In-memory skill list caching with deterministic keys, IntentCoreOptions builders from tool args, response formatters (text/JSON with pretty-printing), and case-insensitive query matching across multiple skill fields.
Tool Implementations
packages/intent-mcp/src/server.ts (lines 117–275)
Three MCP tools: intent_search filters/queries skills with result capping (1–25) and match/warning/conflict counts; intent_load retrieves exact skill by use and wraps content in tagged blocks with formatted metadata; intent_status summarizes package/skill/warning/conflict counts. All tools wrap execution in try/catch, converting errors to MCP text format.
CLI Entry Point
packages/intent-mcp/src/index.ts
Node.js CLI executable that constructs an MCP stdio transport, instantiates the intent MCP server, and connects both components using top-level await.
Test Fixtures
packages/intent-mcp/tests/fixtures/empty/package.json, packages/intent-mcp/tests/fixtures/workspace/package.json
Minimal fixture packages (intent-mcp-empty-fixture and intent-mcp-workspace-fixture) for testing tool behavior under different skill discovery scenarios.
Test Harness & Assertions
packages/intent-mcp/tests/server.test.ts
In-memory transport test infrastructure linking a client and server; verifies tool listing, JSON output formatting, skill search/filtering/capping, skill content rendering with markers, and error handling when skills are missing.
Documentation & Navigation
docs/config.json, docs/getting-started/mcp-server.md
New MCP Server Quick Start guide documenting client configuration (Claude Desktop, cURL examples), tool behavior, debug mode, read-only server semantics, and package discovery from project root; navigation config updated to include the guide.

🎯 3 (Moderate) | ⏱️ ~20 minutes


🐰 Hop along the MCP trail, where skills are cached and queries prevail!
Search, load, and status—three tools in one,
Agents discovering Intent, having such fun!
Stdio transport connects with top-level await,
A read-only server that's truly first-rate! 🚀

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Description check ⚠️ Warning The PR description provides a comprehensive summary of changes and implementation details, but it does not follow the required template structure with the specified sections and checklist items. Restructure the description to match the template: include '## 🎯 Changes' section with motivation, add '## ✅ Checklist' with the two required checkboxes, and add '## 🚀 Release Impact' section with changeset information.
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title '[feat]: add MCP server' clearly and concisely summarizes the primary addition of this PR—a new MCP server package with Intent skill discovery/loading tools.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch mcp

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

  • Generate code and open pull requests
  • Plan features and break down work
  • Investigate incidents and troubleshoot customer tickets together
  • Automate recurring tasks and respond to alerts with triggers
  • Summarize progress and report instantly

Built for teams:

  • Shared memory across your entire org—no repeating context
  • Per-thread sandboxes to safely plan and execute work
  • Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@nx-cloud
Copy link
Copy Markdown

nx-cloud Bot commented May 11, 2026

View your CI Pipeline Execution ↗ for commit de02a31

Command Status Duration Result
nx run-many --targets=build --exclude=examples/** ✅ Succeeded <1s View ↗

☁️ Nx Cloud last updated this comment at 2026-05-11 01:39:55 UTC

@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new Bot commented May 11, 2026

Open in StackBlitz

npm i https://pkg.pr.new/TanStack/intent/@tanstack/intent@131
npm i https://pkg.pr.new/TanStack/intent/@tanstack/intent-mcp@131

commit: ea4cc91

@codspeed-hq
Copy link
Copy Markdown

codspeed-hq Bot commented May 11, 2026

Merging this PR will not alter performance

✅ 6 untouched benchmarks


Comparing mcp (ea4cc91) with main (94a7a82)1

Open in CodSpeed

Footnotes

  1. No successful run was found on main (307f466) during the generation of this report, so 94a7a82 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
packages/intent-mcp/tests/server.test.ts (1)

1-7: 💤 Low value

Reorder imports to satisfy ESLint.

The linter expects Node.js built-in imports (node:path, node:url) to come before external package imports. This is a style convention that improves consistency.

♻️ Suggested import order
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { Client } from '@modelcontextprotocol/sdk/client/index.js'
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { createIntentMcpServer } from '../src/server.js'

As per coding guidelines indicated by ESLint import/order rule.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/intent-mcp/tests/server.test.ts` around lines 1 - 7, Reorder the
import statements so Node built-ins come first: move the node:path import
(dirname, join) and node:url import (fileURLToPath) above external package
imports (Client from '@modelcontextprotocol/sdk/client/index.js' and
InMemoryTransport from '@modelcontextprotocol/sdk/inMemory.js'), then keep type
imports (McpServer) and testing imports (afterEach, beforeEach, describe,
expect, it) followed by the local createIntentMcpServer import; this satisfies
ESLint import/order without changing any identifiers or functionality.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@package.json`:
- Line 30: The npm script "test:intent-mcp" currently uses a POSIX-style env
assignment (TMPDIR=/tmp ...) which fails on Windows; update the script value in
package.json to use cross-env (e.g., prefix with "cross-env TMPDIR=/tmp") and
ensure "cross-env" is added to devDependencies so the script is portable across
platforms; keep the rest of the script ("vitest run --root packages/intent-mcp")
unchanged.

In `@packages/intent-mcp/src/server.ts`:
- Around line 1-11: The import block violates lint rules: reorder and normalize
imports and use explicit type-only imports; group external modules first (node
built-ins then third-party packages) then local/internal modules, sort imports
alphabetically within each group, and convert type imports to "import type" for
IntentCoreOptions, IntentSkillList, and IntentSkillSummary; ensure McpServer is
imported from '@modelcontextprotocol/sdk/server/mcp.js' and non-type symbols
(IntentCoreError, listIntentSkills, loadIntentSkill) are regular imports so the
import/order, sort-imports, and import/consistent-type-specifier-style rules are
satisfied.

---

Nitpick comments:
In `@packages/intent-mcp/tests/server.test.ts`:
- Around line 1-7: Reorder the import statements so Node built-ins come first:
move the node:path import (dirname, join) and node:url import (fileURLToPath)
above external package imports (Client from
'@modelcontextprotocol/sdk/client/index.js' and InMemoryTransport from
'@modelcontextprotocol/sdk/inMemory.js'), then keep type imports (McpServer) and
testing imports (afterEach, beforeEach, describe, expect, it) followed by the
local createIntentMcpServer import; this satisfies ESLint import/order without
changing any identifiers or functionality.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8d575a83-bb89-4863-8155-b6ae46889886

📥 Commits

Reviewing files that changed from the base of the PR and between 307f466 and ea4cc91.

⛔ Files ignored due to path filters (1)
  • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
📒 Files selected for processing (10)
  • docs/config.json
  • docs/getting-started/mcp-server.md
  • package.json
  • packages/intent-mcp/package.json
  • packages/intent-mcp/src/index.ts
  • packages/intent-mcp/src/server.ts
  • packages/intent-mcp/tests/fixtures/empty/package.json
  • packages/intent-mcp/tests/fixtures/workspace/package.json
  • packages/intent-mcp/tests/server.test.ts
  • packages/intent-mcp/tsconfig.json

Comment thread package.json
"generate-docs": "node scripts/generate-docs.ts",
"test:docs": "node scripts/verify-links.ts",
"test:eslint": "nx affected --target=test:eslint --exclude=examples/**",
"test:intent-mcp": "TMPDIR=/tmp vitest run --root packages/intent-mcp",
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Make test:intent-mcp cross-platform.

Line 30 uses POSIX-style env var assignment, which won’t run on Windows shells.

Portable option
-    "test:intent-mcp": "TMPDIR=/tmp vitest run --root packages/intent-mcp",
+    "test:intent-mcp": "cross-env TMPDIR=/tmp vitest run --root packages/intent-mcp",

And add cross-env to devDependencies if it isn’t already present.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@package.json` at line 30, The npm script "test:intent-mcp" currently uses a
POSIX-style env assignment (TMPDIR=/tmp ...) which fails on Windows; update the
script value in package.json to use cross-env (e.g., prefix with "cross-env
TMPDIR=/tmp") and ensure "cross-env" is added to devDependencies so the script
is portable across platforms; keep the rest of the script ("vitest run --root
packages/intent-mcp") unchanged.

Comment on lines +1 to +11
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import {
IntentCoreError,
listIntentSkills,
loadIntentSkill,
type IntentCoreOptions,
type IntentSkillList,
type IntentSkillSummary,
} from '@tanstack/intent/core'
import { resolve } from 'node:path'
import { z } from 'zod'
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Fix import style/order to satisfy current lint rules.

Line 1–Line 11 currently violate import/order, sort-imports, and import/consistent-type-specifier-style. This will keep lint red for the new package.

Proposed fix
+import { resolve } from 'node:path'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import {
   IntentCoreError,
   listIntentSkills,
   loadIntentSkill,
-  type IntentCoreOptions,
-  type IntentSkillList,
-  type IntentSkillSummary,
 } from '@tanstack/intent/core'
-import { resolve } from 'node:path'
+import type {
+  IntentCoreOptions,
+  IntentSkillList,
+  IntentSkillSummary,
+} from '@tanstack/intent/core'
 import { z } from 'zod'
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import {
IntentCoreError,
listIntentSkills,
loadIntentSkill,
type IntentCoreOptions,
type IntentSkillList,
type IntentSkillSummary,
} from '@tanstack/intent/core'
import { resolve } from 'node:path'
import { z } from 'zod'
import { resolve } from 'node:path'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import {
IntentCoreError,
listIntentSkills,
loadIntentSkill,
} from '@tanstack/intent/core'
import type {
IntentCoreOptions,
IntentSkillList,
IntentSkillSummary,
} from '@tanstack/intent/core'
import { z } from 'zod'
🧰 Tools
🪛 ESLint

[error] 6-6: Member 'IntentCoreOptions' of the import declaration should be sorted alphabetically.

(sort-imports)


[error] 6-6: Prefer using a top-level type-only import instead of inline type specifiers.

(import/consistent-type-specifier-style)


[error] 7-7: Prefer using a top-level type-only import instead of inline type specifiers.

(import/consistent-type-specifier-style)


[error] 8-8: Prefer using a top-level type-only import instead of inline type specifiers.

(import/consistent-type-specifier-style)


[error] 10-10: node:path import should occur before import of @modelcontextprotocol/sdk/server/mcp.js

(import/order)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/intent-mcp/src/server.ts` around lines 1 - 11, The import block
violates lint rules: reorder and normalize imports and use explicit type-only
imports; group external modules first (node built-ins then third-party packages)
then local/internal modules, sort imports alphabetically within each group, and
convert type imports to "import type" for IntentCoreOptions, IntentSkillList,
and IntentSkillSummary; ensure McpServer is imported from
'@modelcontextprotocol/sdk/server/mcp.js' and non-type symbols (IntentCoreError,
listIntentSkills, loadIntentSkill) are regular imports so the import/order,
sort-imports, and import/consistent-type-specifier-style rules are satisfied.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant