VUFIND-1809: Add Model Context Protocol (MCP) server support #4939

maccabeelevine · 2025-12-05T00:16:13Z

Per VUFIND-1809, from https://modelcontextprotocol.io/docs/getting-started/intro

MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems.
Using MCP, AI applications like Claude or ChatGPT can connect to data sources (e.g. local files, databases), tools (e.g. search engines, calculators) and workflows (e.g. specialized prompts)—enabling them to access key information and perform tasks.
Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect electronic devices, MCP provides a standardized way to connect AI applications to external systems.

This extends VuFind's existing API capabilities to provide an MCP server, i.e. to respond to MCP queries from AI models.

TODO

maccabeelevine · 2025-12-05T00:26:19Z

This POC doesn't do anything useful yet (check out the amazing addition function), but it is a working MCP server embedded in VuFind. Next step will be to build some real capabilities, i.e. searching and document retrieval.

The implementation adapts the SDK's example of Symfony integration as well as the work @demiankatz is doing on #4672.

There would be some major dependency roadblocks to actually integrating this into VuFind, as I mentioned on the Jira. This POC uses the official PHP SDK, mcp/sdk, which fails to install because it requires "psr/container": "^2.0" while several of our current dependencies are stuck targeting the 1.x releases.

maccabeelevine · 2025-12-05T00:41:32Z

Note for testing, I've locally modified the vendor file (yes I know) laminas-servicemanager/src/ServiceManager to make the has constructor compatible with psr/container 2.

public function has($name): bool

maccabeelevine · 2025-12-05T00:43:56Z

module/VuFindApi/config/module.config.php

    'vufind_api' => [
        'register_controllers' => [
            \VuFindApi\Controller\AdminApiController::class,
+            // \VuFindApi\Controller\McpController::class,


I'm not sure whether this actually belongs in VuFindApi, and if so whether it should be discoverable from the main API endpoint, given the protocol is quite different. To consider.

Perhaps @EreMaijala will have an opinion on this.

module/VuFindApi/src/VuFindApi/Controller/McpController.php

module/VuFindApi/src/VuFindApi/Mcp/ServerProviderFactory.php

maccabeelevine · 2025-12-05T00:52:04Z

You can test the server in a couple of ways:

The official MCP Inspector tool
Via VS Code's chat panel, after adding the MCP server via MCP: Add server

either way, hitting a URL like http://localhost:[port]/vufind/api/v1/mcp

maccabeelevine · 2025-12-05T19:39:49Z

This POC doesn't do anything useful yet (check out the amazing addition function), but it is a working MCP server embedded in VuFind. Next step will be to build some real capabilities, i.e. searching and document retrieval.

It now does a basic keyword search, and record retrieval by ID.

maccabeelevine · 2025-12-05T21:25:51Z

There would be some major dependency roadblocks to actually integrating this into VuFind, as I mentioned on the Jira. This POC uses the official PHP SDK, mcp/sdk, which fails to install because it requires "psr/container": "^2.0" while several of our current dependencies are stuck targeting the 1.x releases.

To get around this, I've temporarily forked php-sdk to allow it to use "psr/container": "^1.1.2 || ^2.0". This at least resolves all of the build errors, while we work on getting rid of all the old laminas dependencies that are stuck using ^1.0.0.

maccabeelevine · 2025-12-09T16:57:57Z

config/vufind/SearchApiRecordFields.yaml

+recordPageFullUrl:
+  vufind.method: "Formatter::getRecordPageFullUrl"
+  description: Link to the record page from external sites with a fully qualified URL
+  type: string


Will extract this to a separate PR

config/vufind/ModelContextProtocol.yaml

maccabeelevine · 2025-12-09T18:29:02Z

module/VuFindApi/src/VuFindApi/Mcp/Capabilities/AbstractSearch.php

+     *
+     * @return array The record
+     */
+    #[McpResourceTemplate(


I'm conflicted about keeping these attributes. In a simple MCP server they are a great, quick way to define its capabilities. But they don't support variable data, or i18n, or dynamic enabling, so in practice they need to be paired with the yaml configuration. As a counter-example I have tools currently defined entirely via yaml, but that leads to bloated configuration (the json schema is pretty verbose) that I don't love either.

I am leaning to just consistently use the yaml config for every capability, verbose but consistent. but open to other thoughts.

maccabeelevine · 2025-12-12T21:22:12Z

module/VuFindApi/src/VuFindApi/Controller/McpController.php

+        }
+
+        // $content = json_decode($this->params()->getController()->getRequest()->getContent(), true);
+        // $mcpMethod = $content['method'] ?? '';


I have to think through if this is useful. Methods in MCP are not specific enough, i.e. all tools are method "tools/call" and you need a further param "name" to know what's actually being called. But if we go down the route of allowing selective methods/names, then I also have to consider the fact that "tools/list" would list them all. Etc. for resources, prompts, etc. It's probably a good start just to indivisibly allow or disallow MCP. Of course the permissions.ini still lets you narrow down that single permission by IP address, etc.

maccabeelevine · 2025-12-12T21:23:31Z

module/VuFindApi/src/VuFindApi/Controller/McpController.php

+    protected function outputAuthError(string $messageId): Response
+    {
+        $error = new Error($messageId, $this->AUTH_ERROR, 'Access denied');
+        $response = $this->getResponse();


Much of this is borrowed from ApiTrait. Not sure if it's worth refactoring that method for the few bits that are useful here.

config/vufind/ModelContextProtocol.yaml

maccabeelevine · 2025-12-30T18:53:54Z

To get around this, I've temporarily forked php-sdk to allow it to use "psr/container": "^1.1.2 || ^2.0". This at least resolves all of the build errors, while we work on getting rid of all the old laminas dependencies that are stuck using ^1.0.0.

Forking is no longer necessary, as the upstream php-sdk now supports earlier psr/container.

demiankatz

Thanks, @maccabeelevine, I took a first look through this. I'm not yet familiar with the libraries and technologies being used, so I mainly focused on general design and documentation for this initial pass.

demiankatz · 2026-01-07T14:35:45Z

config/vufind/ModelContextProtocol.yaml

+General:
+  # Enable the MCP Server and register all capabilities defined below. Disabled by default.
+  # Access must also be granted in permissions.ini.
+  # enabled: true


Would it be better to have either enabled: false or #enabled: true here? Usually we only put a comment-space before a descriptive comment, and a comment-no-space before a disabled setting... but with YAML being so finicky about whitespace, anything we can do to reduce the chances of the user messing up indentation will be helpful!

(And whatever pattern we decide on here we should probably try to apply to other commented-out stuff below).

demiankatz · 2026-01-07T14:42:05Z

config/vufind/ModelContextProtocol.yaml

+
+General:
+  # Enable the MCP Server and register all capabilities defined below. Disabled by default.
+  # Access must also be granted in permissions.ini.


Worth mentioning the specific access.mcp permission here while we're at it? Or is this intentionally vague for flexibility?

demiankatz · 2026-01-07T14:42:45Z

module/VuFindApi/config/module.config.php

    'vufind_api' => [
        'register_controllers' => [
            \VuFindApi\Controller\AdminApiController::class,
+            // \VuFindApi\Controller\McpController::class,


Perhaps @EreMaijala will have an opinion on this.

demiankatz · 2026-01-07T14:44:25Z

composer.json

        "process-timeout": 0,
        "allow-plugins": {
            "composer/package-versions-deprecated": true,
+            "php-http/discovery": true,


Is this needed? If so, how is it used?

demiankatz · 2026-01-07T14:48:30Z

module/VuFindApi/src/VuFindApi/Mcp/ServerProvider.php

+        }
+
+        $builder = Server::builder()
+            ->setServerInfo(name: 'VuFind Server', version: '0.0.1', description: 'The library catalog')


Should add the ® symbol here. Might also be nice to replace the description with the title value from config.ini.

Suggested change

->setServerInfo(name: 'VuFind Server', version: '0.0.1', description: 'The library catalog')

->setServerInfo(name: 'VuFind® Server', version: '0.0.1', description: 'The library catalog')

demiankatz · 2026-01-07T14:52:56Z

module/VuFindApi/src/VuFindApi/Mcp/Capabilities/AbstractSearch.php

+     *
+     * @return string
+     */
+    abstract protected function getSearchClassId();


Might as well add return types when defining new functions...

Suggested change

abstract protected function getSearchClassId();

abstract protected function getSearchClassId(): string;

demiankatz · 2026-01-07T14:53:03Z

module/VuFindApi/src/VuFindApi/Mcp/Capabilities/AbstractSearch.php

+     *
+     * @return string
+     */
+    protected function getRequestParam()


Suggested change

protected function getRequestParam()

protected function getRequestParam(): string

demiankatz · 2026-01-07T14:53:18Z

module/VuFindApi/src/VuFindApi/Mcp/Capabilities/SearchSolr.php

+     *
+     * @return string
+     */
+    protected function getSearchClassId()


Suggested change

protected function getSearchClassId()

protected function getSearchClassId(): string

demiankatz · 2026-01-07T14:54:15Z

module/VuFindApi/src/VuFindApi/Mcp/Capabilities/AbstractSearch.php

+    public function searchRecords(string $keywords, ?string $contentType = null): array
+    {
+        $limit = $this->limit;
+        $rawRequest = [$this->getRequestParam() => urldecode($keywords)];


Do we really expect $keywords to come in url-encoded? Is that normal?

demiankatz · 2026-01-07T14:56:32Z

module/VuFindApi/src/VuFindApi/Formatter/RecordFormatter.php

+     *
+     * @return string
+     */
+    protected function getRecordPageFullUrl($record)


We'll need to be sure to reconcile this with #4954 when that is done.

Add Model Context Protocol (MCP) server support

a09b710

Fix a test

c85e87d

maccabeelevine commented Dec 5, 2025

View reviewed changes

module/VuFindApi/src/VuFindApi/Controller/McpController.php Outdated Show resolved Hide resolved

maccabeelevine commented Dec 5, 2025

View reviewed changes

module/VuFindApi/src/VuFindApi/Mcp/ServerProviderFactory.php Outdated Show resolved Hide resolved

maccabeelevine added 4 commits December 5, 2025 13:16

Remove unneeded factory

0fb6107

Add resource template for record by ID

e505480

Add resource template to search by keywords

a1943c6

Change the catalog search resource template to an MCP tool

8edc6df

maccabeelevine added 2 commits December 5, 2025 21:10

Use forked mcp/sdk (for now) that supports psr/container 1.x

ff615de

Fix constructor

388cf91

maccabeelevine added 2 commits December 5, 2025 22:16

Alphabetize composer.json and avoid the comma problem

b38b285

Allow filtering on content type, and introduce config

2fa7562

maccabeelevine commented Dec 9, 2025

View reviewed changes

config/vufind/ModelContextProtocol.yaml Show resolved Hide resolved

maccabeelevine added 3 commits December 9, 2025 17:28

Fix url formatting

4064814

Allow configuration of resource templates

9f06a06

Fix template definition

9ca27db

maccabeelevine commented Dec 9, 2025

View reviewed changes

maccabeelevine added 4 commits December 12, 2025 15:06

Fix style

1875304

Add basic authorization checks via permissions.ini

b60de62

Add some typing

c5f0864

Fix messageId

2db7cca

maccabeelevine commented Dec 12, 2025

View reviewed changes

maccabeelevine added 3 commits December 30, 2025 15:07

Use mcp/sdk 0.2.2, which supports older psr/container

13ac656

Validate contentType

0f02770

Document .yaml file

320a1b4

maccabeelevine commented Dec 30, 2025

View reviewed changes

config/vufind/ModelContextProtocol.yaml Outdated Show resolved Hide resolved

maccabeelevine added 2 commits December 30, 2025 17:50

Refactor capabilities and support auto-discovery

3cd81f2

Link to wiki

dc72670

demiankatz requested changes Jan 7, 2026

View reviewed changes

EreMaijala mentioned this pull request Jan 16, 2026

Official MCP support in Finna samuli/finna-mcp#1

Open

	->setServerInfo(name: 'VuFind Server', version: '0.0.1', description: 'The library catalog')
	->setServerInfo(name: 'VuFind® Server', version: '0.0.1', description: 'The library catalog')

	abstract protected function getSearchClassId();
	abstract protected function getSearchClassId(): string;

	protected function getRequestParam()
	protected function getRequestParam(): string

	protected function getSearchClassId()
	protected function getSearchClassId(): string

VUFIND-1809: Add Model Context Protocol (MCP) server support #4939

Are you sure you want to change the base?

VUFIND-1809: Add Model Context Protocol (MCP) server support #4939

Uh oh!

Conversation

maccabeelevine commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maccabeelevine commented Dec 5, 2025

Uh oh!

maccabeelevine commented Dec 5, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

maccabeelevine commented Dec 5, 2025

Uh oh!

maccabeelevine commented Dec 5, 2025

Uh oh!

maccabeelevine commented Dec 5, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maccabeelevine Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

maccabeelevine commented Dec 30, 2025

Uh oh!

demiankatz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

maccabeelevine commented Dec 5, 2025 •

edited

Loading

maccabeelevine Dec 12, 2025 •

edited

Loading