Download the PHP package suzumaze/bear-sunday-mcp-server without Composer

BEAR.Sunday MCP Server

Read-only MCP adapter for the BEAR.Sunday Semantic API exposed by suzumaze/bear-phpactor-extension through the Phpactor Language Server.

The adapter contains no Resource URI, Router, SQL, template, ALPS, or JSON Schema resolution rules. Phpactor remains the single semantic implementation used by both IDEs and AI clients.

Status

The server provides twenty-four read-only tools against BEAR Semantic API version 1 and Phpactor's standard LSP. In addition to project, Resource, and schema facts, it resolves explicit Route names, SQL query IDs, Twig/Qiq template names, Resource templates, and ALPS descriptors. It also exposes allowlisted Resource attribute facts, a bounded attribute inventory, presence-only contract comparison, static Resource references, and incoming Link/Embed relations. Project-level contract coverage distinguishes absent, dynamic, unresolved, available, and non-applicable JSON Schema and ALPS surfaces without treating optional adoption gaps as errors. Project diagnostics and contract coverage use stable offset pagination and an approximate serialized-byte budget: a page can be shorter than its requested count. Advance offset by the actual returned item count while truncated is true. Diagnostics accepts limit 1–200 (default 100); contract coverage accepts 1–100 (default 100). A single oversized item may exceed the budget. gapsOnly selects adoption gaps without returning covered rows. Use scheme: "page" or "app" to select a source URI family before pagination. For a first overview, request a small page (for example limit: 10 or 20). total, scan metadata, and contract-coverage summary still describe the whole scan; fetch further pages only when the question requires their rows. This reduces returned content, not scanning work or the host's tool-definition overhead. A complete audit must follow truncated to the end, advancing by the actual returned item count. Project-report text fallbacks retain the same full result as structuredContent, encoded as compact JSON to avoid the additional whitespace of SDK pretty printing. Hosts may surface one or both representations, so this reduces wire bytes but does not promise a specific model-token saving. The scheme alone does not establish whether a Resource is publicly exposed or rendered as JSON; absent does not mean a Schema is required. On hosts that support the open MCP Apps UI extension, bear_contract_coverage also renders a coverage view with surface distributions, App/Page URI subtotals, Resource-method filtering, inline contract details, and prominent scan-truncation warnings. Selecting a method can ask the host assistant to inspect its workspace-relative source path; editor navigation depends on the host. The path can also be copied. The view loads no external resources and does not replace the tool's text and structuredContent response on other hosts. Definition, Type Definition, References, and Hover can be queried at a position in a saved workspace file; Completion, Document Links, document symbols, and workspace symbol search are also available. Workspace symbol search covers Phpactor's indexed class, function, and constant records, not methods, and does not claim that its index is current.

See 日本語) for the implemented boundary, real-workspace verification evidence, and deferred experiments. See the 日本語の全24ツール一覧) for the complete inventory, and 日本語) for task-oriented workflows.

Requirements

• PHP 8.2 or newer
• Phpactor with suzumaze/bear-phpactor-extension 0.1.8 or newer installed in Phpactor's Composer environment
• An MCP host that supports stdio servers

bear_contract_coverage additionally requires a Phpactor extension build that advertises the contractCoverage capability; older compatible extensions return engine_unavailable for that single tool while the remaining tools continue to work.

The MCP SDK is fixed to the compatible 0.8.x line because its public API is not yet 1.0.

Install

Install the released server into a dedicated directory:

For development from the repository instead:

Use the Phpactor binary configured by phpactor-setup-for-bear-sunday or another Phpactor installation that actually loads the BEAR extension. You do not need a second Phpactor installation when the setup package already provides one.

Run directly

--workspace is required and canonicalized once at startup. --phpactor may be omitted. The adapter then checks PHPACTOR_BIN, WORKSPACE/vendor/bin/phpactor, and finally the phpactor command on PATH. A configured command is passed directly to proc_open as an argument array; shell command strings and appended arguments are rejected.

The process normally appears to wait silently because MCP messages use stdin and stdout.

Configure Codex

Register one BEAR.Sunday workspace with Codex CLI:

Codex CLI, the Codex app, and the Codex IDE extension on the same host share MCP configuration. Restart the app or IDE extension after adding the server; use /mcp in the CLI to inspect it. See the Codex MCP documentation.

The equivalent ~/.codex/config.toml entry is:

Configure Claude Code

Register the server for one local project without committing machine-specific paths:

Use /mcp inside Claude Code to inspect the connection and available tools. See the Claude Code MCP documentation.

For a trusted project shared by a team, use --scope project or commit an .mcp.json file. Do not commit personal absolute paths; use paths valid for every team member or document the required substitution.

Configure another MCP client

For MCP hosts that use an mcpServers JSON object:

The initial transport is local stdio. Browser-only Claude.ai or ChatGPT sessions cannot start this local process directly; supporting those environments would require a separately secured Streamable HTTP deployment.

Each configured server is fixed to one workspace. Give entries distinct names, such as bear-project-a and bear-project-b, when using multiple BEAR.Sunday projects.

Connect a generic LSP client

An editor, CLI, or AI client with native LSP support can skip MCP and start Phpactor directly:

Standard clients can use Definition, Type Definition, References, Hover, Completion, Document Link, Document Symbols, and Workspace Symbols. A client able to send custom requests can also call the read-only bear/* Semantic API directly. MCP is only the adapter that presents selected custom requests as named AI tools.

Try it from an AI client

After connecting, ask the client for facts rather than naming tools explicitly:

For task-oriented walkthroughs, result interpretation, and a comparison with text search, see 日本語).

Optional agent skill

MCP exposes the tools, while the bundled bear-semantic skill teaches an agent when to prefer them over text search, how to interpret bounded results, and how to verify an authorized edit. Install the skills/bear-semantic directory using the normal skill mechanism of your AI client. It is optional and does not become a Composer dependency of the BEAR.Sunday application.

The skill checks bear_project_info first and falls back to standard LSP navigation, rg, and source inspection when this MCP server is unavailable. Tool schemas and safety rules remain in the server, so the MCP interface is usable without the skill.

Tools

The complete Japanese reference is available in MCPツール一覧.

Every result keeps the core envelope unchanged:

Failures are tool results with stable semantic statuses rather than PHP exception traces. An unsupported Semantic API major version returns unsupported. Missing Phpactor or a missing custom LSP method returns engine_unavailable.

data is present and non-null only when status is ok; Phpactor's stdio serializer omits null object members. A failed semantic query may include an optional partial object containing narrower facts established before the failure. For example, bear_template_for_resource returns not_found without success data and preserves the resolved Resource and searched convention paths in partial when only the template is missing. Clients must continue to use status, not the presence of partial, for success or failure.

lsp_workspace_symbols.data.coverage records the exact boundary: Phpactor class, function, and constant index records are included; methods are not. Its provenance uses freshness: "unknown" because a saved workspace file does not prove that Phpactor has indexed a newly created file. Treat not_found as inconclusive and use lsp_document_symbols for a known file or source search for unsupported member discovery.

Safety model

• All MCP tools declare readOnlyHint: true, destructiveHint: false, and openWorldHint: false.
• No MCP tool accepts a command, executable path, workspace root, URL, or arbitrary LSP method.
• The workspace root and Phpactor command are fixed before the MCP server starts.
• The adapter never runs the BEAR application, renders templates, edits files, or accesses the network.
• Semantic responses come only from saved workspace files through the core's canonical path and symlink checks.
• Position tools reject traversal and outside-workspace symlinks, read at most 1 MiB per saved document, and temporarily open that exact snapshot through standard LSP.
• Standard LSP results expose workspace-relative paths only, with at most 200 result items, 64 KiB of Hover text, and 8 KiB per Completion or Symbol text field.
• MCP and LSP frames, paths, result counts, timeouts, and retained child-process stderr are bounded.
• Malformed tool input is rejected by JSON Schema without terminating the server.

JetBrains prior art

The read-only BEAR semantic tools in bearsunday/idea-php-bearsunday-plugin are important prior art. They use JetBrains indexes and the IDE MCP server. This package is different in one deliberate way: it is a headless stdio bridge to Phpactor, so IDE navigation and MCP queries share the same transport-independent BEAR query layer.

No JetBrains source code is copied into this repository.

Development

The normal suite uses a fake LSP server and exercises MCP initialize, tools/list, and tools/call over real stdio processes. To additionally run against a real Phpactor binary:

The real tests exercise every published MCP tool through a real Phpactor process, verify Semantic API version 1, and confirm that an outside-workspace context path is rejected without exposing the outside path.

Deferred scope

The original standard-LSP discovery scope is now covered. Additional methods will be added only when they expose concrete BEAR or Phpactor value through a bounded, method-specific schema; the adapter will not expose an arbitrary LSP passthrough.

Design notes for integrating agent workflows without moving subjective policy into the semantic core are documented in BEAR.Skills integration (Japanese). The proposed read-only boundary for optional runtime cache evidence is documented in BEAR.QueryRepository semantic log integration (Japanese).

License

MIT