feat: implement the new internal MCP configuration spec #226

MQ37 · 2025-08-19T22:48:31Z

closes #215

Important changes

I had to make the call-actor tool two step since the LLM would refuse to fetch Actor details with input schema first and would hallucinate input. There is now new param step (info (default) and call), the info returns the Actor details card same as fetch-actor-details (yes, it is duplicite but I think it makes sense, what is user adds just this tool - it should be self-contained) and in step call it runs the actual Actor with the provided input.

Generated Summary

This PR aligns the server configuration with the new tools configuration spec, simplifying how tools and actors are selected and making defaults more predictable. It also reworks tool categories and deprecates legacy flags.

TL;DR (New Spec)

tools can include categories or specific tools: You can configure the server to load full categories or individual tools.
Example: tools=storage,runs loads two categories; tools=add-actor loads just one tool.
enableAddingActors=true maps to tools=add-actor: The legacy flag is deprecated. It’s replaced by tools=add-actor (now part of the experimental category). For backward compatibility, the old flag is mapped internally.
actors merged into tools: Previously always enabled; now part of the tools param logic. If no tools param is passed, the category remains enabled by default.
call-actor enabled by default: Previously behind preview, it now loads automatically when no tools param is provided. We’ll improve its description for better UX.
CLI still uses --tools and now supports tool names: No format change; you can specify tool names in addition to category names.
Tool categories reworked: Categories were cleaned up to match the new selection model.

What Changed

• Input Normalization and Selection

Reworked processInput to:
- Normalize actors/tools from strings or arrays.
- Deprecate and map enableActorAutoLoading → enableAddingActors.
- Merge actors into tools so selection lives in one place (actors now behave like tool selectors).
- Make enableAddingActors default to false and rely on explicit tools=add-actor or the experimental category.
Updated URL parsing: actors= query now populates tools selectors.

• Server and Startup

createExpressApp(host) no longer accepts mcpServerOptions. The server reads request-level inputs (including tools) rather than global startup options.
ActorsMcpServer is constructed without the prior options bag; configuration is derived per request via normalized inputs.
Standby mode simplified: it starts the app and defers tool selection to per-request parameters.

• Tools and Categories

Introduced single-tool selection (e.g., tools=add-actor).
experimental category can include add-actor; selecting the category or the tool directly loads it even if enableAddingActors is false.
call-actor is enabled by default when no tools param is present.
Reworked exports to use addTool from src/tools/helpers.ts; removed legacy addRemoveTools export.

• Tests and Internal Utilities

Updated integration and unit tests to the new selection semantics.
Adjusted expectations: no longer rely on counts that included default actors or legacy add/remove tools; assert named presence instead.
Improved resilience of input parsing and tool merging behavior.

• Rename

Tool get-actor-details → fetch-actor-details (rename noted here and will be finalized shortly).

Breaking Changes

createExpressApp no longer accepts the mcpServerOptions object; callers should rely on per-request tools selection (via URL/CLI/env).
enableAddingActors is now default false; use tools=add-actor (or include experimental) to expose it.
actors is no longer a separate always-on path; it’s merged into tools.

Notable Files Touched

src/input.ts
src/mcp/server.ts
src/actor/server.ts
src/main.ts
src/tools/helpers.ts
src/tools/index.ts
src/utils/tools-loader.ts
tests/** — updated to reflect new semantics

…by import of getActorsAsTools and pass it as internal tool arg instead.

MQ37 · 2025-08-21T13:48:30Z

sorry guys, quite a large PR with a bit of refactoring. The main thing is to thoroughly review the test cases and see if they make sense in context of the new spec and if we are not missing any scenario @jirispilka @MichalKalita

src/input.ts

src/utils/tools-loader.ts

tests/integration/suite.ts

jirispilka

I really like it. Thank you, great job.

My only concern is with getActorsTools, which is being passed to addTool. Please try to remove this.

Please also update manifest.json so that it corresponds to the new tools specs.

src/tools/actor.ts

src/mcp/server.ts

src/input.ts

tests/unit/input.test.ts

README.md

fix: Delete clients (in examples). They are not used and outdated anyway. Also update README.md

Co-authored-by: Jiří Spilka <[email protected]>

…r internal repo

… exposed tools (#218) * feat(input): allow empty tools and actors to allow greater control of exposed tools * revert internals * more robust input processing * fix(docs): update tool categories and add usage notes in README * fix(manifest): update default values for tool categories and dynamic Actor adding * feat: implement the new internal MCP configuration spec (#226) * feat: refactor and unify input handling, remove unnecessary logic * feat: vibe new mcp input spec * fix: remove unnecessary addTool in mcp/server.ts * fix: fix stdio.only add-actor tool related circular dependency cause by import of getActorsAsTools and pass it as internal tool arg instead. * fix test suite, clean up * fix tests and logic to adhere to the new spec * refactor code * lint * rename to fetch-actor-details * improve readme * update stdio help * improve test case names * fix and improve the call-actor generic tool * more spec new spec complience tests * lint * one more test, just in case * address pr comment and refactor the process input func * fix: Delete example clients, update Readme (#239) fix: Delete clients (in examples). They are not used and outdated anyway. Also update README.md * Update tests/unit/input.test.ts Co-authored-by: Jiří Spilka <[email protected]> * Update tests/unit/input.test.ts Co-authored-by: Jiří Spilka <[email protected]> * Update README.md Co-authored-by: Jiří Spilka <[email protected]> * address review comments * clean up imports and update comments for clarity, export functions for internal repo --------- Co-authored-by: Jiří Spilka <[email protected]> * update dxt manifest --------- Co-authored-by: Jiří Spilka <[email protected]>

MQ37 added 13 commits August 19, 2025 23:07

feat: refactor and unify input handling, remove unnecessary logic

0bb8397

feat: vibe new mcp input spec

abc22ca

fix: remove unnecessary addTool in mcp/server.ts

f06d72e

fix: fix stdio.only add-actor tool related circular dependency cause …

2e41b61

…by import of getActorsAsTools and pass it as internal tool arg instead.

fix test suite, clean up

f326b73

fix tests and logic to adhere to the new spec

662aba1

refactor code

48301cd

lint

fd1436f

rename to fetch-actor-details

4944f34

improve readme

4763f51

update stdio help

92c1244

improve test case names

f969ac2

fix and improve the call-actor generic tool

3869388

MQ37 self-assigned this Aug 21, 2025

MQ37 changed the title ~~feat: vibe new mcp input spec~~ feat: implement the new internal MCP configuration spec Aug 21, 2025

more spec new spec complience tests

47e93f2

MQ37 marked this pull request as ready for review August 21, 2025 13:46

lint

8419e13

MQ37 requested review from MichalKalita and jirispilka August 21, 2025 13:48

one more test, just in case

7bebb9c

MichalKalita reviewed Aug 22, 2025

View reviewed changes

src/input.ts Outdated Show resolved Hide resolved

src/utils/tools-loader.ts Show resolved Hide resolved

src/utils/tools-loader.ts Show resolved Hide resolved

tests/integration/suite.ts Show resolved Hide resolved

address pr comment and refactor the process input func

5799ebe

jirispilka requested changes Aug 23, 2025

View reviewed changes

jirispilka and others added 5 commits August 24, 2025 20:14

fix: Delete example clients, update Readme (#239)

ac81747

fix: Delete clients (in examples). They are not used and outdated anyway. Also update README.md

Update tests/unit/input.test.ts

ceafe8b

Co-authored-by: Jiří Spilka <[email protected]>

Update tests/unit/input.test.ts

495c465

Co-authored-by: Jiří Spilka <[email protected]>

Update README.md

3e7d9e8

Co-authored-by: Jiří Spilka <[email protected]>

address review comments

240793a

clean up imports and update comments for clarity, export functions fo…

3947d1e

…r internal repo

MQ37 requested a review from jirispilka August 26, 2025 06:49

MQ37 merged commit fa5a747 into feat/tools-actors-input-allow-empty Aug 26, 2025
3 checks passed

MQ37 deleted the feat/vibe-mcp-spec branch August 26, 2025 07:44

MQ37 removed the request for review from jirispilka August 26, 2025 07:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: implement the new internal MCP configuration spec #226

feat: implement the new internal MCP configuration spec #226

Uh oh!

MQ37 commented Aug 19, 2025 •

edited

Loading

Uh oh!

MQ37 commented Aug 21, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jirispilka left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: implement the new internal MCP configuration spec #226

feat: implement the new internal MCP configuration spec #226

Uh oh!

Conversation

MQ37 commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Generated Summary

TL;DR (New Spec)

What Changed

• Input Normalization and Selection

• Server and Startup

• Tools and Categories

• Tests and Internal Utilities

• Rename

Breaking Changes

Notable Files Touched

Uh oh!

MQ37 commented Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jirispilka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

MQ37 commented Aug 19, 2025 •

edited

Loading

MQ37 commented Aug 21, 2025 •

edited

Loading