feat(forest mcp): make the mcp server ready to be used as a route instead of standalone

[VincentMolinie]

Definition of Done

General

• Write an explicit title for the Pull Request, following Conventional Commits specification
• Test manually the implemented changes
• Validate the code quality (indentation, syntax, style, simplicity, readability)

Security

• Consider the security impact of the changes made

[VincentMolinie]

https://app.clickup.com/t/86c70j2jk

[qltysh]

1 new issue

Tool	Category	Rule	Count
qlty	Structure	Function with high complexity (count = 14): buildExpressApp	1

[qltysh]

Total Coverage: Coverage tags mismatch: head has [] but base only has []

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[EnkiP]

this change do move the parser before oauth handlers, is that ok ?

[Scra3]

PR Review Summary

Overview

This PR introduces a new @forestadmin/mcp-server package (~5900 lines added) providing HTTP REST API access to Forest Admin operations with OAuth authentication support.

---

Critical Issues (4 found - Must Fix)

Issue	File	Line
Silent OAuth initialization failure allows server to start in broken state	forest-oauth-provider.ts	51-58
Unsafe error.message access on unknown type - will crash on non-Error	forest-oauth-provider.ts	193, 236
Missing auth data validation - undefined values passed to RPC client	agent-caller.ts	9-15
Type assertion without null check on JWT decode result	forest-oauth-provider.ts	275-283

---

Important Issues (8 found - Should Fix)

Issue	File	Line
Potential info disclosure via error messages in OAuth redirect	forest-oauth-provider.ts	158-166
CORS set to origin: '*' - security consideration	server.ts	127-130
Hardcoded scopes in verifyAccessToken bypasses access control	forest-oauth-provider.ts	339-340
Token revocation silently does nothing (security)	forest-oauth-provider.ts	364-372
Silent failure in getClient hides server errors	forest-oauth-provider.ts	104-121
Activity log failure blocks main operation	list.ts	83-85
Global schema cache shared across instances	schema-fetcher.ts	49
README missing environment variables documentation	README.md	35-39

---

Test Coverage Gaps (7 found)

Gap	File	Criticality
getFieldsOfCollection error when collection not found	schema-fetcher.test.ts	8/10
Network failure in fetchForestSchema	schema-fetcher.test.ts	8/10
Unknown error re-throw in verifyAccessToken	forest-oauth-provider.test.ts	8/10
Expired server token handling in generateAccessToken	forest-oauth-provider.test.ts	7/10
Missing baseUrl error in buildExpressApp	server.test.ts	7/10
Network failure in activity log creation	activity-logs-creator.test.ts	6/10
revokeToken basic behavior test	forest-oauth-provider.test.ts	5/10

---

Documentation Issues (3 found)

Issue	File
Missing FOREST_URL, FOREST_SERVER_URL, FOREST_FRONTEND_HOSTNAME env vars	README.md
Incomplete API endpoints documentation (OAuth endpoints not mentioned)	README.md
FIXME comment in revokeToken lacks ticket/context	forest-oauth-provider.ts

---

Strengths ✓

1. Comprehensive test coverage across OAuth flows, activity logs, filters, and error parsing
2. Good use of Zod for runtime validation
3. Proper OAuth error classes from MCP SDK
4. Clean separation of concerns between server, provider, tools, and utilities
5. Helpful error messages for invalid sort fields with field suggestions

---

Recommended Fixes

1. Fix Critical Issues First

// forest-oauth-provider.ts:193 - Fix unsafe error access
} catch (error) {
  const message = error instanceof Error ? error.message : String(error);
  throw new InvalidRequestError(`Failed to exchange authorization code: ${message}`);
}

// agent-caller.ts:9-15 - Add validation
const token = request.authInfo?.token;
const url = request.authInfo?.extra?.environmentApiEndpoint;
if (!token) throw new Error('Authentication token is missing');
if (!url || typeof url !== 'string') throw new Error('Environment API endpoint is missing');

2. Address Security Issues

• Sanitize error messages in OAuth redirects (don't expose internal errors to clients)
• Implement proper scope handling in verifyAccessToken
• Either implement token revocation or throw NotImplemented error
• Consider making CORS configurable

3. Add Missing Tests

Focus on error paths with criticality ≥ 7/10

4. Update Documentation

• Add missing environment variables to README
• Document all API endpoints (OAuth endpoints)

---

🤖 Generated with Claude Code

[EnkiP]

apply fixes about claude review