@evref-bl/pharo-mcp 2.2.0 → 3.0.0

package/README.md

@@ -32,6 +32,22 @@ Metacello new
    load.
 ```
 
+The baseline groups are:
+
+- `Core`: the server, its transport and schema machinery, and the catalog
+  tools it dispatches through
+- `IDE`: the image tools — classes, methods, packages, tests, critiques,
+  repositories, change history, debugging
+- `UI`: the world-menu server list
+- `Telemetry`: the OpenTelemetry backend
+- `default`: `Core`, `IDE`, `UI` and their tests
+
+A project embedding the server and serving tools of its own loads `Core` alone,
+which leaves out the image tools and everything behind them. Loading its package
+is all its tools need: a tool that names itself is in the catalog.
+[Building on MCP](templates/pharo-references/building-on-mcp.md) walks through
+a tool, a resource and a prompt of your own.
+
 Start the Streamable HTTP server:
 
 ```smalltalk
@@ -51,6 +67,7 @@ and first calls.
 - [Documentation index](docs/README.md)
 - [Getting started](templates/pharo-references/getting-started.md)
 - [Using MCP from an agent](templates/pharo-references/using-pharo-mcp.md)
+- [Building on MCP](templates/pharo-references/building-on-mcp.md)
 - [Tool reference](templates/pharo-references/tool-reference.md)
 - [Safety and ecosystem integration](templates/pharo-references/safety-and-ecosystem.md)
 - [Troubleshooting](templates/pharo-references/troubleshooting.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-mcp",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "Pharo MCP agent-host templates",
   "license": "MIT",
   "type": "module",

package/templates/pharo-references/building-on-mcp.md

@@ -0,0 +1,473 @@
+# Building On MCP
+
+MCP is a server you can embed. Loading `Core` gives you the Streamable HTTP
+transport, the JSON-RPC and schema machinery and the catalog tools, and
+nothing that knows about Pharo code. Everything the server then offers a
+client — tools, resources, prompts — you write in a package of your own.
+
+A project doing this changes nothing in MCP. Its tools live in a package of
+its own, which it loads when it wants them served and leaves out when it does
+not.
+
+## Load the server alone
+
+Depend on the baseline and ask for `Core`:
+
+```smalltalk
+BaselineOfMyProject >> baseline: spec
+
+	<baseline>
+	spec for: #common do: [
+		spec baseline: 'MCP' with: [
+			spec
+				repository: 'github://Evref-BL/MCP:vX.Y.Z/src';   "a release, not a branch"
+				loads: #( 'Core' ) ].
+		spec package: 'MyProject-MCP' with: [ spec requires: #( 'MyProject' 'MCP' ) ].
+		spec group: 'Tools' with: #( 'MyProject-MCP' ).
+		spec group: 'default' with: #( 'Core' 'Tests' ) ]
+```
+
+Two things in it are worth copying. The group is named `Tools` rather than
+`MCP`, because Metacello refuses a group and a baseline that share one name.
+And it is left out of `default`: your project is useful without a server, and
+an image that does not serve MCP has no use for tools it cannot register.
+
+The other groups are `IDE`, MCP's own image tools for classes, methods,
+packages, tests, repositories, change history and debugging; `UI`,
+the world-menu server list; `Telemetry`, the OpenTelemetry backend; and
+`default`, which is `Core`, `IDE`, `UI` and their tests.
+
+## The three things a server offers
+
+| Kind | What it is | Who reaches for it | Subclass of | Names itself with |
+| --- | --- | --- | --- | --- |
+| Tool | an action with arguments | the model, on its own | `MCPTool` | `toolName` |
+| Resource | a document to read | the host, for the user | `MCPResource` | `resourceUri` |
+| Prompt | a message template | the user, deliberately | `MCPPrompt` | `promptName` |
+
+They are independent. A server may have one of them, two, or all three.
+
+## A tool
+
+Give your tools a common superclass. It is where the things they share live —
+the group they belong to, the icon they are drawn with, the helpers that talk
+to your project:
+
+```smalltalk
+MCPTool << #MyProjectTool
+	package: 'MyProject-MCP'
+```
+
+```smalltalk
+MyProjectTool class >> groupName
+
+	^ 'widgets'
+```
+
+The base is not served, and needs to say nothing to stay out: it answers no
+`toolName`, so there is no tool there to register.
+
+Then one class per tool:
+
+```smalltalk
+MyProjectTool << #MyProjectToolListWidgets
+	package: 'MyProject-MCP'
+```
+
+```smalltalk
+MyProjectToolListWidgets class >> toolName
+
+	^ 'widget_list'
+
+MyProjectToolListWidgets >> title
+
+	^ 'List Widgets'
+
+MyProjectToolListWidgets >> description
+
+	^ 'List the widgets this image holds, optionally those whose name starts with a prefix. Use widget_get to read one.'
+
+MyProjectToolListWidgets >> additionalKeywords
+
+	^ #( 'widget' 'inventory' )
+
+MyProjectToolListWidgets >> annotations
+
+	^ MCPStructureToolAnnotations readOnly
+
+MyProjectToolListWidgets >> buildInputSchema
+
+	^ MCPStructureInputSchema new
+		  type: 'object';
+		  properties: { (self
+				   schemaPropertyNamed: 'prefix'
+				   type: 'string'
+				   description: 'Only answer widgets whose name starts with this. Defaults to all of them.') };
+		  required: #(  );
+		  yourself
+
+MyProjectToolListWidgets >> executeWithRequest: request
+
+	| prefix names |
+	prefix := request stringArgumentNamed: 'prefix' default: ''.
+	names := (MyProject widgetNames select: [ :each | each beginsWith: prefix ]) asArray sorted.
+	^ self
+		  successResultText: names size asString , ' widget(s): ' , (', ' join: names) , '.'
+		  data: { (#widgets -> names) } asDictionary
+```
+
+`MyProject widgetNames` stands for your own code. What the rest is for:
+
+- **`toolName`** is the key in one catalog shared with every other tool the
+  image has loaded, so pick a first word that is yours. `widget_list` is
+  safe; `class_search` is taken.
+- **`description`** is read by a model deciding whether to call you. Say what
+  the tool answers and name the tools that come next, the way the example
+  points at `widget_get`.
+- **`additionalKeywords`** are the words `tool_search` matches besides the
+  ones already in the name and title.
+- **`annotations`** tell a client what the tool does to the image.
+  `MCPStructureToolAnnotations readOnly` promises it changes nothing;
+  `mayModify` says otherwise. A host may require a confirmation for the
+  second.
+- **`buildInputSchema`** is the contract the server validates an incoming
+  call against before your code runs. `additionalProperties` defaults to
+  false, so a caller that misspells an argument is told so instead of having
+  it ignored. Every property takes a description; it is the only place the
+  caller learns what the argument means.
+
+## Being served
+
+A tool is served because its package was loaded, and naming itself is how a
+class says it is a tool. Nothing else is needed: load `MyProject-MCP` and
+every server in the image has `widget_list`.
+
+It is the tool's **own** name that serves it, not an inherited one. A
+subclass of a tool is a variation of that tool, so specialising one does not
+claim the name it already holds — give the subclass its own `toolName` when
+it is a tool of its own.
+
+A class that must stay out of every catalog says so itself:
+
+```smalltalk
+MyProjectTestTool class >> shouldAutoRegister
+
+	^ false
+```
+
+That is the right thing for a test fixture, which would otherwise be served
+by every server in the image whose tests are loaded.
+
+## Reading arguments
+
+`executeWithRequest:` receives an `MCPToolRequest` whose arguments have
+already been validated against your schema. Read them with the typed
+accessors rather than by hand, so a missing or oddly typed value fails in one
+place:
+
+```smalltalk
+request stringArgumentNamed: 'name'.
+request stringArgumentNamed: 'name' default: 'anything'.
+request stringArgumentNamed: 'side' in: #( 'instance' 'class' ) default: 'instance'.
+request booleanArgumentNamed: 'force' default: false.
+request nonNegativeIntegerArgumentNamed: 'offset' default: 0.
+request stringCollectionArgumentNamed: 'packages' default: #(  ).
+request hasArgumentNamed: 'prefix'.
+```
+
+## Answering
+
+Two answers, both built by the tool:
+
+```smalltalk
+self successResultText: 'Three widgets.' data: { (#widgets -> names) } asDictionary.
+self errorResultText: 'No widget named ' , name , '.' details: { (#known -> names) } asDictionary
+```
+
+The text is what a model reads; the data is the same answer in a shape a
+program can use. Give both. A text that says only "Done." costs the caller
+another round trip to find out what happened.
+
+You do not have to catch to report a failure. An exception that escapes
+`executeWithRequest:` is answered as an error result naming your tool, the
+error class, the message and the frames of your own code; the server leaves
+its own frames out. Build an error result yourself when you know something
+the exception does not, such as what the caller should have asked for.
+
+Which of the two reaches the client is the server's choice, not the tool's.
+`toolResponseFields` defaults to `#content`, where the data is rendered into
+the text. `useContentAndStructuredContentToolResponses` sends both, and
+`useStructuredContentOnlyToolResponses` sends only the structured half. The
+structured half carries your text as `summary` and your dictionary as `data`.
+
+### Answering a page
+
+A tool that answers a list answers one page of it, so a long result never
+arrives as one block a model has to read through. Three parts: the shared
+`offset` argument, how big a page is, and the slicing. The listing tool
+again, now that the list can be long:
+
+```smalltalk
+MyProjectToolListWidgets >> buildInputSchema
+
+	^ MCPStructureInputSchema new
+		  type: 'object';
+		  properties: { self offsetInputProperty };
+		  required: #(  );
+		  yourself
+
+MyProjectToolListWidgets >> defaultPageLimit
+
+	^ 25
+
+MyProjectToolListWidgets >> executeWithRequest: request
+
+	| page |
+	page := MCPPaginationResult
+		        fromEntries: MyProject widgetNames asArray sorted
+		        limit: self defaultPageLimit
+		        offset: (request nonNegativeIntegerArgumentNamed: 'offset' default: 0).
+	^ self
+		  successResultText: page returnedCount asString , ' widget(s).'
+		  data: (page asDictionaryWithEntriesKey: #widgets)
+```
+
+`offsetInputProperty` is the same `offset` argument every paging tool takes,
+declared once so they all describe it the same way. `MCPPaginationResult`
+cuts the page and answers the shape MCP's own tools answer: your entries
+under the key you name, a `pagination` summary beside them, and `nextOffset`
+while entries remain — a caller asks again with that offset until it stops
+coming.
+
+Answering `defaultPageLimit` is what puts `pageSize` in your contract, so
+`tool_get` can tell a caller how large a page is before asking for one. A
+tool that answers a whole result rather than pages leaves it alone.
+
+## Groups and icons
+
+`groupName` is how the catalog and the world-menu browser group related
+tools. Pick one for your project and answer it on the shared superclass.
+
+MCP reads an icon out of a tool name whose words it recognises — `class`,
+`method`, `search`, `create` — which is how its own tools stay consistent
+without anyone choosing. Your words are not in that vocabulary, so declare an
+icon:
+
+```smalltalk
+MyProjectTool class >> toolIconSpec
+
+	^ MCPToolIconSpec baseIconNamed: #pharoHalfScale badgeIconNamed: #browse
+```
+
+## A resource
+
+A resource is a document the host can put in front of the model without the
+model asking. Where a tool answers a question, a resource is material:
+
+```smalltalk
+MCPResource << #MyProjectWidgetResource
+	package: 'MyProject-MCP'
+```
+
+```smalltalk
+MyProjectWidgetResource class >> resourceUri
+
+	^ 'myproject://widgets'
+
+MyProjectWidgetResource class >> resourceName
+
+	^ 'widgets'
+
+MyProjectWidgetResource >> title
+
+	^ 'Widget Inventory'
+
+MyProjectWidgetResource >> description
+
+	^ 'Every widget this image holds, as JSON.'
+
+MyProjectWidgetResource >> mimeType
+
+	^ 'application/json'
+
+MyProjectWidgetResource >> readContents
+
+	^ self textContents: (STONJSON toStringPretty: { (#widgets -> MyProject widgetNames) } asDictionary)
+```
+
+The URI is the key in the registry, and the same rule applies: a resource
+that names itself is served.
+
+### A family of resources
+
+When the document is one of many, named by something in the URI, subclass
+`MCPResourceTemplate`. It names itself with a `resourceUriTemplate` in RFC
+6570 form, resolves one URI at a time through `resourceForUri:`, and may
+suggest values for its variables:
+
+```smalltalk
+MyProjectWidgetTemplate class >> resourceUriTemplate
+
+	^ 'myproject://widget/{name}'
+
+MyProjectWidgetTemplate >> resourceForUri: aUri
+
+	| name |
+	(aUri beginsWith: MyProjectOneWidgetResource resourceUri) ifFalse: [ ^ nil ].
+	name := aUri allButFirst: MyProjectOneWidgetResource resourceUri size.
+	^ name
+		  ifEmpty: [ nil ]
+		  ifNotEmpty: [ MyProjectOneWidgetResource named: name ]
+
+MyProjectWidgetTemplate >> completionsFor: aVariableName value: aPrefix context: aContextDictionary
+
+	aVariableName = 'name' ifFalse: [ ^ #(  ) ].
+	^ MyProject widgetNames select: [ :each | each beginsWith: aPrefix ]
+```
+
+A template lists through `resources/templates/list` and never answers
+contents of its own.
+
+What it resolves to is an ordinary resource built per URI rather than
+registered. It carries the name it was built with, answers its own `uri`, and
+keeps itself out of the catalog, where one entry standing for the whole family
+would be wrong:
+
+```smalltalk
+MyProjectOneWidgetResource class >> resourceUri
+
+	^ 'myproject://widget/'
+
+MyProjectOneWidgetResource class >> shouldAutoRegister
+
+	^ false
+
+MyProjectOneWidgetResource class >> named: aName
+
+	^ self new
+		  widgetName: aName;
+		  yourself
+
+MyProjectOneWidgetResource >> uri
+
+	^ self class resourceUri , self widgetName
+
+MyProjectOneWidgetResource >> name
+
+	^ self widgetName
+
+MyProjectOneWidgetResource >> readContents
+
+	^ self textContents: (MyProject describeWidgetNamed: self widgetName)
+```
+
+## A prompt
+
+A prompt is user-controlled where a tool is model-controlled: a client
+usually shows them as slash commands, so a prompt is something a person
+reaches for deliberately.
+
+```smalltalk
+MyProjectReviewPrompt class >> promptName
+
+	^ 'review_widget'
+
+MyProjectReviewPrompt >> title
+
+	^ 'Review A Widget'
+
+MyProjectReviewPrompt >> description
+
+	^ 'Asks for a review of one widget.'
+
+MyProjectReviewPrompt >> arguments
+
+	^ { (MCPStructurePromptArgument name: 'widget' description: 'The widget to review.' required: true) }
+
+MyProjectReviewPrompt >> messagesFor: anArgumentDictionary
+
+	^ self userMessage: 'Review the widget named ' , (anArgumentDictionary at: 'widget')
+		  , ' and say what you would change.'
+```
+
+Like a template, a prompt may answer `completionsFor:value:context:` for its
+own arguments.
+
+## Shaping the server's surface
+
+Two words govern it. A **registered** tool is in the catalog: callable by
+name, and findable with `tool_search` and `tool_get`. An **advertised** tool
+is also in `tools/list`, which is the list a client shows a model up front.
+Advertising decides what is shown, not what may be called.
+
+A tool from outside MCP is registered and discoverable, not advertised, so it
+costs nothing in the client's context until something looks for it. Answer
+`'static'` from `defaultExposure` to be in `tools/list` from the start.
+
+Against that default, a server is configured directly:
+
+```smalltalk
+mcp := MCP new.
+mcp addTool: MyProjectToolListWidgets.          "or addTools: { A. B }"
+mcp removeTool: 'image_evaluate'.
+mcp advertiseTool: MyProjectToolListWidgets.    "adds one to what is advertised"
+mcp advertiseTools: { MyProjectToolListWidgets }. "replaces the advertised set"
+mcp advertiseAllTools.
+mcp advertiseToolDefaults.
+mcp port: 4000.
+mcp start.
+```
+
+`MCP startOnPort:` on the class side answers the server already on that port,
+or builds one with the default catalog. A server you configured is started
+through the instance, as above.
+
+For a server holding only your own tools:
+
+```smalltalk
+mcp := MCP onlyTools: { MyProjectToolListWidgets. MyProjectToolGetWidget }.
+mcp port: 4000.
+mcp start.
+```
+
+`onlyTools:` replaces the catalog with exactly those, advertises all of them,
+and discovers nothing afterwards. That includes the catalog tools: a server
+built this way has no `tool_search`, `tool_get` or `tool_call` unless you add
+them back. Add `MCPToolSearchTools`, `MCPToolGetTool` and `MCPToolCallTool`
+when you want a surface a model can explore, or build up from `MCP new` with
+`addTool:` instead.
+
+## Testing what you serve
+
+A server answers its JSON-RPC methods as plain messages, so a test needs no
+socket and no port:
+
+```smalltalk
+MyProjectToolTest >> testListingAnswersEveryWidget
+
+	| result |
+	result := (MCP new useContentAndStructuredContentToolResponses; yourself)
+		          rpcToolCall: 'widget_list' withParams: Dictionary new.
+	self assert: (((result at: #structuredContent) at: #data) at: #widgets) equals: #( 'alpha' 'beta' 'gamma' ).
+	self assert: (((result at: #content) first at: #text) beginsWith: '3 widget(s)')
+```
+
+Assert on the data rather than on the whole text: under the default
+`#content`, the text a client receives is your summary with the data rendered
+underneath it, so an equality test on it breaks whenever either half changes.
+
+`rpcResourceRead:`, `rpcPromptGet:arguments:`, `rpcToolsList`,
+`rpcResourcesList` and `rpcPromptsList` are there for the same purpose.
+
+## Things that bite
+
+- **A name already taken.** The catalog holds one tool per name. Prefix with
+  a word that is yours.
+- **A subclass of an existing tool is not served** until it names itself.
+  That is deliberate: it would otherwise claim its superclass's name and the
+  two would race for the key.
+- **A fixture in a loaded test package is served** like anything else.
+  Answer `false` from `shouldAutoRegister`.
+- **`onlyTools:` drops the catalog tools.** See above.
+- **Nothing is saved.** Tools change the running image and never write it to
+  disk. `Smalltalk saveSession` is the caller's business, not the tool's.

package/templates/pharo-references/safety-and-ecosystem.md

@@ -275,7 +275,8 @@ makes one only when the image has none there. Starting a second server on a
 taken port fails after a couple of seconds, and the error now says when the
 port is held by another MCP in the same image.
 
-An inspected `MCP` object has two Spec tabs. The dashboard runs the server:
+An inspected `MCP` object has a dashboard tab and an observability tab. The
+dashboard runs the server:
 
 - server status, endpoint and port
 - debug mode

package/templates/pharo-references/tool-reference.md

@@ -43,10 +43,10 @@ mcp useContentAndStructuredContentToolResponses.
 ## Compact Paging
 
 List and search tools are optimized for low token usage. A page is the tool's
-own size, chosen for what one of its entries costs to read: fifty classes,
-twenty-five methods or packages, twenty critique hits, ten repositories. When
-another page exists, `data` includes `nextOffset`; call the same tool again
-with that `offset` to continue.
+own size, chosen for what one of its entries costs to read, so a page of
+classes is longer than a page of repositories. The number is not something to
+know in advance: when another page exists, `data` includes `nextOffset`; call
+the same tool again with that `offset` to continue.
 
 A search answers what identifies each hit, not everything known about it.
 `repository_search` says how many packages a repository holds rather than
@@ -55,7 +55,7 @@ rather than restating its documentation on every hit.
 
 ## Naming Several Targets
 
-Four tools act on several targets in one call. The argument that names the
+Some tools act on several targets in one call. The argument that names the
 target holds either one value or a list of them, and every other argument
 applies to all of them:
 
@@ -124,7 +124,7 @@ attempted.
 
 ## The Advertised Surface
 
-Fifteen tools are advertised directly: `tool_search`, `tool_get`, `tool_call`, `class_search`, `class_get`, `class_create`, `class_remove`, `method_search`, `method_source_search`, `method_reference_search`, `method_get`, `method_compile`, `method_remove`, `test_run` and `image_evaluate`. Every other tool is found with `tool_search` and called by name like any other; `tool_call` does the same for a client that will only send a name its own list holds.
+What a client is shown up front is the advertised surface: the catalog tools, the everyday class and method operations, `test_run` and `image_evaluate`. Which ones exactly is what `tools/list` answers, and the client already holds that list, so read it there rather than from here. Every other tool is found with `tool_search` and called by name like any other; `tool_call` does the same for a client that will only send a name its own list holds.
 
 A server chooses its own surface before `start`:
 

package/templates/pharo-references/troubleshooting.md

@@ -37,7 +37,7 @@ http://127.0.0.1:4000
 
 If you changed the port in Pharo, update the MCP client configuration.
 
-MCP currently handles MCP calls over HTTP POST. Unsupported HTTP methods
+MCP handles MCP calls over HTTP POST. Unsupported HTTP methods
 return method-not-allowed instead of hanging.
 
 ## `tools/list` Is Empty Or Stale

package/templates/pharo-references/using-pharo-mcp.md

@@ -77,96 +77,10 @@ Run `npx @evref-bl/pharo-mcp install --host <host>` in the target project to
 install context-routed skills for project loading, version compatibility,
 image-to-Git handoff, CI reproduction, and standalone MCP recovery.
 
-## Custom Tools
+## Serving Your Own
 
-Define custom tools as subclasses of `MCPTool` in your own package. At minimum,
-provide the class-side tool name and the instance-side metadata, schema, and
-execution protocol expected by `MCPTool`:
-
-```smalltalk
-MCPTool << #MyProjectMCPTool
-	slots: {};
-	package: 'MyProject-MCP'
-```
-
-```smalltalk
-MyProjectMCPTool class >> toolName
-
-	^ 'my_project_tool'
-
-MyProjectMCPTool >> description
-
-	^ 'Do one project-specific operation.'
-
-MyProjectMCPTool >> buildInputSchema
-
-	^ MCPStructureInputSchema new
-		type: 'object';
-		properties: #(  );
-		required: #(  );
-		additionalProperties: false;
-		yourself
-
-MyProjectMCPTool >> executeWithRequest: request
-
-	^ self
-		successResultText: 'Operation completed.'
-		data: Dictionary new
-```
-
-By default, tools outside the MCP package are not auto-registered. If your
-package intentionally publishes a tool whenever it is loaded, opt in:
-
-```smalltalk
-MyProjectMCPTool class >> shouldAutoRegister
-
-	^ true
-```
-
-Auto-registered external tools are discoverable by default. Agents can find
-them with `tool_search`, inspect them with `tool_get`, and call them by name.
-
-`MCPToolRegistry` is the server's source of truth for registered tools. In
-normal use, configure it through the `MCP` instance messages below. The
-`tools/list` response contains only the static tool surface cached by the MCP
-instance; discoverable tools remain callable, and are found with `tool_search`
-and `tool_get`.
-
-Two words govern the surface. A **registered** tool is in the catalog, found
-with `tool_search` and `tool_get`, and callable. An **advertised** tool is also
-in `tools/list`. Advertising decides what a client is shown, not what it may
-call.
-
-For a server with only your own tools:
-
-```smalltalk
-mcp := MCP onlyTools: { MyProjectMCPTool }.
-mcp start.
-```
-
-`onlyTools:` replaces the catalog with exactly those tools and advertises all of
-them. Advertise a subset when some registered tools should stay discoverable
-through the catalog tools instead:
-
-```smalltalk
-mcp := MCP onlyTools: { MyProjectMCPTool. MyOtherMCPTool }.
-mcp advertiseTools: { MyProjectMCPTool }.
-```
-
-To add to the tools a server already has, rather than replacing them:
-
-```smalltalk
-mcp := MCP new.
-mcp addTool: MyProjectMCPTool.
-mcp start.
-```
-
-`addTool:` takes a class or a ready instance, and `addTools:` takes several.
-`removeTool:` takes one back out by name. `advertiseTools:` accepts classes,
-instances or names, and registers anything not in the catalog yet, so it can be
-called before or after adding. `advertiseAllTools` advertises everything, and
-`advertiseToolDefaults` returns to each tool's own default exposure.
-
-Use `defaultExposure` to decide whether a registered tool is directly
-advertised in `tools/list` (`'static'`) or kept discoverable through the catalog
-tools (`'discoverable'`, the default).
+An image can serve tools, resources and prompts a project defines itself,
+from that project's own package and without changing MCP. Read
+[Building on MCP](building-on-mcp.md) for the server-only load, what a tool,
+a resource and a prompt each need, and how the surface a client sees is
+shaped.

package/templates/pharo.AGENTS.md

@@ -31,6 +31,8 @@ guessing from source.
   `skills/pharo-mcp-recovery/SKILL.md`.
 - Before debugger sessions or repairs: read the local
   [debugging guide](pharo-references/debugging.md).
+- Before giving a project MCP tools, resources or prompts of its own: read
+  [building on MCP](pharo-references/building-on-mcp.md).
 
 ## Workflow