feat(mcp-server): add create tool

[Scra3]

Summary

• Add new create MCP tool to create records in a collection
• Accepts collectionName and attributes object
• Handles LLM sending attributes as JSON string (preprocessing)
• Activity logging with 'create' action
• Returns the created record

Dependencies

This PR is based on #1387 (feat/delete) and should be merged after it.

Test plan

• Unit tests for create tool (14 tests)
• All mcp-server tests pass (349 tests)

🤖 Generated with Claude Code

[qltysh]

1 new issue

Tool	Category	Rule	Count
qlty	Structure	Function with many parameters (count = 4): declareCreateTool	1

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (1)

Rating	File	% Diff	Uncovered Line #s
	packages/agent/src/agent.ts	100.0%
	Total	100.0%

🚦 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.

[Scra3]

PR Review Summary

Overview

This PR adds a new create tool and refactors existing tools to use a withActivityLog utility for centralized activity log lifecycle management. Overall good DRY refactoring.

---

🔴 Critical Issue (1)

Activity log failure blocks operations

File: with-activity-log.ts:34-37

If createPendingActivityLog throws (network error, auth issue, server unavailable), the entire operation fails before business logic runs. Activity logging should be non-blocking - users should still be able to perform operations even if Forest Admin server is temporarily unavailable.

Suggestion: Wrap createPendingActivityLog in try/catch and continue with operation even if it fails:

let activityLog;
try {
  activityLog = await createPendingActivityLog(...);
} catch (err) {
  logger('Error', `Failed to create activity log: ${err}`);
}
// Continue with operation

---

🟡 Important Issues (4)

1. Lost error context in list-related.ts

Lines 28-76

parseAgentError was removed from enhanceErrorWithContext. The original code extracted nested JSON API error details, now it only uses error.message. Users will see raw JSON error payloads instead of clean messages.

2. Inconsistent error parsing in list.ts

Lines 131-148

The error handling now relies on raw error message after withActivityLog already parsed it. When parseAgentError returns null, the original unparsed error is thrown, and the "Invalid sort" check may fail on nested JSON.

3. Silent schema fetch failure

File: list-related.ts:68-71

Empty catch block with no logging when schema fetch fails during error enhancement. Consider adding debug logging.

4. Inconsistent error handling patterns

list and list-related have extra try/catch outside withActivityLog, while create and describe-collection don't. This makes error handling architecture unclear.

---

💡 Suggestions

1. describe-collection.ts:101 - Uses action: 'index' but this tool describes schema, not lists records. Consider adding a comment explaining this choice.

2. create.ts:13-17 - Silent JSON parse fallback. Consider adding debug logging when JSON parsing fails.

3. Missing test - No test for createPendingActivityLog failure in with-activity-log.test.ts.

---

✅ Strengths

• Good DRY refactoring with withActivityLog utility
• Smart LLM handling in attributesWithPreprocess (handles JSON strings)
• Comprehensive test coverage for new utility
• Proper test updates for refactored tools

[VincentMolinie]

That's bad 😅
Cna you make that dynamic

[Scra3]

Yes ofc