feat(mcp): add typed Airbyte Agents entity tools - #1132
feat(mcp): add typed Airbyte Agents entity tools#1132Aaron ("AJ") Steers (aaronsteers) wants to merge 2 commits into
Conversation
Co-Authored-By: AJ Steers <aj@airbyte.io>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
👋 Greetings, Airbyte Team Member!Here are some helpful tips and reminders for your convenience. 💡 Show Tips and TricksTesting This PyAirbyte VersionYou can test this version of PyAirbyte using the following: # Run PyAirbyte CLI from this branch:
uvx --from 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1787878218-agents-entity-tools' pyairbyte --help
# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1787878218-agents-entity-tools'PR Slash CommandsAirbyte Maintainers can execute the following slash commands on your PR:
📚 Show Repo GuidanceHelpful ResourcesCommunity SupportQuestions? Join the #pyairbyte channel in our Slack workspace. |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
There was a problem hiding this comment.
🔍 Devin Review: 1 flag
Not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)
There was a problem hiding this comment.
Pull request overview
Adds a dedicated set of typed MCP tools for Airbyte Agents “entity” operations (list/search/get + create/update/delete), providing stricter result shaping and tool-level readonly/destructive hints, and wires them into the MCP server with unit coverage.
Changes:
- Added
airbyte/mcp/agents_entities.pyimplementing six entity-specific MCP tools with typed return models and strict payload coercion. - Registered the new toolset in the MCP server so it appears in the tool list (including readonly/destructive annotations).
- Added unit tests covering paging shape, search action selection, get coercion/rejection cases, write forwarding, and tool annotations.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
airbyte/mcp/agents_entities.py |
New typed entity MCP tools and result models; registration helper for server integration. |
airbyte/mcp/server.py |
Registers the new entity tool module with the FastMCP app. |
airbyte/mcp/__init__.py |
Exposes agents_entities as part of the public airbyte.mcp module exports. |
tests/unit_tests/test_mcp_agent_entities.py |
New unit tests validating typed tool behavior, coercion rules, forwarding, and annotations. |
Suppressed comments (2)
airbyte/mcp/agents_entities.py:339
search_agent_entitiescurrently hard-codesexclude_fields=None, so callers cannot actually use the field-exclusion capability that_execute()already supports.
action="api_search" if use_api_search else "search",
api_args=api_args,
select_fields=select_fields,
exclude_fields=None,
page_size=page_size,
airbyte/mcp/agents_entities.py:397
get_agent_entitycurrently hard-codesexclude_fields=None, so even after adding the parameter it needs to be forwarded into_execute()for it to take effect.
action="get",
api_args=api_args,
select_fields=select_fields,
exclude_fields=None,
page_size=None,
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Co-Authored-By: AJ Steers <aj@airbyte.io>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review. 📝 WalkthroughWalkthroughChangesAgent entity operations
Estimated code review effort: 3 (Moderate) | ~25 minutes Merge Risk: ⚪ Minimal · up to The PR adds typed Agent entity tools while preserving existing workspace, authentication, readonly, and connector execution controls. No actionable merge-blocking risk remains beyond normal checks and review. Sequence Diagram(s)sequenceDiagram
participant MCPClient
participant EntityTool
participant ReadWriteHelper
participant Execute
participant AgentConnector
MCPClient->>EntityTool: invoke entity operation
EntityTool->>ReadWriteHelper: pass action and arguments
ReadWriteHelper->>Execute: execute Agent action
Execute->>AgentConnector: forward connector request
AgentConnector-->>Execute: return action result
Execute-->>ReadWriteHelper: return status and payload
ReadWriteHelper-->>EntityTool: shape entity result
EntityTool-->>MCPClient: return MCP result
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Code Coverage OverviewLanguages: Python Python / code-coverage/pytest-fastThe overall line coverage in commit f32b5a2 in the Show a line coverage summary of the most impacted files.
Python / code-coverage/pytest-no-credsThe overall line coverage in commit f32b5a2 in the Show a line coverage summary of the most impacted files.
Python / code-coverage/pytestThe overall line coverage in commit f32b5a2 in the Show a line coverage summary of the most impacted files.
Updated |
Summary
Requested by AJ Steers as the follow-up to the merged Agents base work (#1127), which shipped the generic pair
execute_agent_connector_ro/execute_agent_connector. Those two are enough to reach any connector action, but they push two costs onto the calling agent: it has to know the action vocabulary, and it gets backresult: Anywith no shape.This adds six action-specific MCP tools in a new
airbyte/mcp/agents_entities.py, all thin presentation over the same hidden_execute()helper the generic tools use — no new transport, no new auth path, no change toairbyte/agents/.Two things this buys beyond naming:
readOnlyHintis a static annotation read by the server's readonly filter before any call, so the generic write-capable tool vanishes whole in readonly mode. The three read tools here are statically read-only, so a readonly deployment can still list, search, and get.Any. The generic result carriesresult: Any; these return the shape the action actually produces — a page (entities,has_next_page,end_cursor), a singleentity | None, or a write ack. Coercion is strict rather than permissive:get_agent_entityraisesPyAirbyteInputErrorif the connector returns more than one entity, and any non-object payload is rejected rather than passed through as a mystery blob.entity_typestays a free string, sinceinspectpublishes only Context Store entities, not everythingexecute()accepts — typing it would reject legitimate calls.Deliberately not done: no seventh tool for
api_search(same read shape assearch, so it's ause_api_searchflag), and no separaterecord/fieldsargument on the writes — the payload stays inapi_args, which is where the connector-specific arguments already live.workspace_idbehaves exactly as in the generic tools: exposed as an argument, hidden when statically configured, and the connector is resolved through its workspace so a connector belonging to another workspace is rejected before any action runs.Test Plan
uv run pytest tests/unit_tests/test_mcp_agent_entities.py tests/unit_tests/test_mcp_agents.py— 13 new cases, 43 total, passing. Covers page shaping and cursor passthrough, theuse_api_searchaction switch, all six coercion outcomes forget_agent_entity(including the multi-match and non-object rejections), per-tool action/payload forwarding on the writes, and a live-server assertion that the read tools register withreadOnlyHint=trueanddelete_agent_entitywithdestructiveHint=true.uv run ruff format/uv run ruff check/uv run pyrefly checkclean.uv run poe mcp-docs-mdregenerates cleanly and emitsdocs/mcp-generated/agents_entities.md(gitignored, generated at build time).cloud-mcp:executeAPI and MCP tools,AgentOrganization, andAgentWorkspace#1127 there are no cassettes for the Agents API.Link to Devin session: https://app.devin.ai/sessions/57a0c3e7b98f4c52a9c09a5cd721ee3a
Open in Devin Desktop: https://app.devin.ai/desktop/session/57a0c3e7b98f4c52a9c09a5cd721ee3a?variant=devin
Requested by: Aaron ("AJ") Steers (@aaronsteers)
Summary by CodeRabbit
New Features
Tests