feat: add mcp & skills

[NathanFlurry]

No description provided.

[railway-app]

🚅 Deployed to the rivet-pr-3992 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
website	❌ Build Failed (View Logs)	Web	Jan 22, 2026 at 10:46 pm
frontend-cloud	🕒 Building (View Logs)	Web	Jan 22, 2026 at 10:45 pm
frontend-inspector	🕒 Building (View Logs)	Web	Jan 22, 2026 at 10:45 pm

[NathanFlurry]

• feat: add mcp & skills #3992 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: feat: add mcp & skills

Summary

This PR adds Model Context Protocol (MCP) support and a comprehensive skill system for RivetKit documentation. The changes include a new MCP hub package for serving documentation via MCP and extensive skill documentation.

Overall Assessment: ✅ Well-implemented with good test coverage. A few minor suggestions for improvement.

---

Code Quality & Best Practices

Strengths

• Excellent test coverage: Both search.test.ts and utils.test.ts provide comprehensive unit tests
• Clean separation of concerns: Search logic, utilities, and MCP server are well-separated
• Good error handling: Proper validation with Zod schemas and meaningful error messages
• Type safety: Strong TypeScript usage throughout
• Well-documented: README provides clear usage examples

Suggestions

1. Error Handling in CLI (rivetkit-typescript/packages/mcp-hub/src/cli.ts:76-78)

The error message in the catch block could be more informative:

main().catch((error) => {
	console.error("Failed to start docs MCP server", error);
	process.exit(1);
});

Suggestion: Add structured error logging:

main().catch((error) => {
	console.error("Failed to start docs MCP server:", {
		message: error.message,
		stack: error.stack,
	});
	process.exit(1);
});

2. Magic Numbers (rivetkit-typescript/packages/mcp-hub/src/index.ts:27-28)

const DEFAULT_LIMIT = 8;

Suggestion: Consider making limits configurable via DocsServerOptions for flexibility.

3. Token Estimation Accuracy (rivetkit-typescript/packages/mcp-hub/src/utils.ts:1-6)

The token estimation uses a hardcoded ratio:

const TOKEN_RATIO = 1.3;

Suggestion: Add a comment explaining this ratio or consider making it configurable since different LLMs may have different tokenization strategies.

4. Shared Transport State (rivetkit-typescript/packages/mcp-hub/src/index.ts:51)

let sharedWebTransport: WebStandardStreamableHTTPServerTransport | null = null;

Concern: Global mutable state could cause issues in concurrent scenarios. Consider documenting thread-safety expectations or using a singleton pattern with proper initialization guards.

---

Potential Bugs or Issues

1. Missing Parent Page Handling

In index.ts:339, when creating section resources:

const parent = pageMap.get(section.parent_uri);
const sectionTitle = parent ? `${parent.title} › ${section.title}` : section.title;

Issue: If parent is missing, it silently falls back to just the section title. This could indicate data integrity issues.

Suggestion: Add logging or throw an error if parent is unexpectedly missing since sections should always have valid parents.

2. Cursor Decode Error Handling

In utils.ts:36-43, cursor decoding silently returns 0 on error:

export function decodeCursor(cursor?: string | null): number {
	if (!cursor) return 0;
	try {
		const decoded = JSON.parse(Buffer.from(cursor, "base64url").toString());
		return typeof decoded.offset === "number" && decoded.offset >= 0 ? decoded.offset : 0;
	} catch {
		return 0;
	}
}

Suggestion: Consider logging the error or adding validation feedback. Malformed cursors could indicate client bugs that should be surfaced.

---

Security Concerns

1. Environment Variable Handling

The code reads DOCS_METADATA_PATH from environment variables without validation:

const customPath = process.env.DOCS_METADATA_PATH;
if (customPath) {
	const absolutePath = path.isAbsolute(customPath) ? customPath : path.resolve(process.cwd(), customPath);

Security: Path traversal could be possible if customPath contains ../ sequences.

Suggestion: Validate the path is within expected directories.

2. CLI Body Parsing (cli.ts:54-73)

The readBody function doesn't have size limits:

for await (const chunk of req) {
	chunks.push(Buffer.from(chunk));
}

Security: Large payloads could cause memory exhaustion.

Suggestion: Add a max body size limit (e.g., 1MB for JSON-RPC).

---

Test Coverage

Strengths

• ✅ Good unit test coverage for utilities (utils.test.ts)
• ✅ Search engine tests cover edge cases (search.test.ts)
• ✅ Mock metadata factory for testing

Gaps

1. Integration tests: No tests for the full MCP server workflow
2. CLI tests: The cli.ts file has no test coverage
3. Error scenarios: Limited testing of error paths in the MCP server

---

Recommendations

High Priority

1. ✅ Add security validation for file paths
2. ✅ Add request body size limits in CLI
3. ✅ Document thread-safety of shared transport

Medium Priority

1. Make configuration more flexible (limits, token ratios)
2. Add integration tests
3. Improve error handling with structured logging
4. Handle missing parent pages explicitly

Low Priority

1. Consider async metadata loading
2. Add performance benchmarks for large doc sets
3. Document the token ratio calculation

---

Conclusion

This is a solid implementation that adds valuable MCP support to the Rivet ecosystem. The code is well-structured, properly tested, and follows TypeScript best practices. The main concerns are around security hardening (path validation, body size limits) and some edge case handling. With the suggested improvements, this will be production-ready.

Recommendation: Approve with minor changes suggested above.

---

Great work on this feature! The MCP integration will significantly improve the developer experience for working with Rivet documentation. 🚀

[jog1t]

https://www.npmjs.com/package/@hono/mcp

[jog1t]

#!/usr/bin/env tsx

[jog1t]

https://github.com/modelcontextprotocol/typescript-sdk?

[graphite-app]

Merge activity

• Jan 22, 10:46 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Jan 22, 10:46 PM UTC: CI is running for this pull request on a draft pull request (#4011) due to your merge queue CI optimization settings.
• Jan 22, 10:47 PM UTC: Merged by the Graphite merge queue via draft PR: #4011.