refactor(errors): unified AgentflareError for MCP dispatch helpers

[getappz]

Summary

Several internal MCP dispatch-layer helpers touch more than one heterogeneous fallible source (mutex lock, rusqlite, a sub-crate registry, agentflare-backend) and manually map each one with .map_err(|e| ErrorData::internal_error(e.to_string(), None))? — repetitive boilerplate the same pattern the codebase already avoids for backend errors via map_backend_err.

Fix

• Adds AgentflareError (src/errors.rs), wrapping: mutex-lock poisoning, rusqlite::Error, std::io::Error, skill_registry::LoadError, agentflare_backend::Error — plus pub type Result<T> = std::result::Result<T, AgentflareError>.
• Adds impl From<AgentflareError> for ErrorData (src/mcp_server.rs, next to map_backend_err, which it delegates to for the Backend variant so existing error-code behavior — INVALID_PARAMS vs internal_error — is unchanged).
• Converts with_fresh_registry, resolve_workspace_id, and claim_db to return crate::errors::Result<T> internally. Their own call sites (skill_search, skill_load, handoff, resolve_project, asset x2) already used ? and needed zero changes — the new From impl is what makes that ? work now that the internal error type is AgentflareError instead of ErrorData directly.

5 explicit .map_err(...) sites collapse to plain ? across the 3 helpers.

Note: this only converts internal helpers, not the giant #[tool]-dispatch match arms in mcp_server.rs — those still return Result<_, ErrorData> directly and are out of scope for this PR (would be a much larger, riskier refactor).

Testing

• cargo test --workspace — 365 passed, 0 failed
• cargo clippy --workspace --all-targets -- -D warnings -A unsafe_code -A clippy::pedantic — clean
• cargo fmt --check — clean

Summary by CodeRabbit

• Bug Fixes
  • Improved error handling across server operations.
  • Errors from locks, storage, file operations, and backend services are now reported more consistently through MCP responses.
  • Reduced the likelihood of unclear or inconsistent internal error messages.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 141a564c-c3e5-47ed-9e92-7d78ffc0f2df

📥 Commits

Reviewing files that changed from the base of the PR and between 82b2908 and 99ef53f.

📒 Files selected for processing (2)

• src/errors.rs
• src/mcp_server.rs

---

📝 Walkthrough

Walkthrough

The change adds a unified AgentflareError and Result alias, centralizes conversion into MCP ErrorData, and updates registry, workspace, and database helpers to propagate errors through the shared conversion path.

Changes

MCP error propagation

Layer / File(s)	Summary
Unified error contract src/errors.rs, src/mcp_server.rs	Defines AgentflareError variants and converts them centrally into MCP ErrorData.
Helper result propagation src/mcp_server.rs	Updates registry, workspace, and database helpers to return crate::errors::Result and use ? propagation.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• getappz/agentflare#165: Adds MCP backend tools with related backend-to-ErrorData error handling.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main refactor and names the new unified error type.
Description check	✅ Passed	The description covers the summary, rationale, implementation, testing, and reviewer notes, with only template headings differing.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.

✨ 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 fix/unified-error-type-for-mcp-dispatch

---

_{Comment @coderabbitai help to get the list of available commands.}