fix(mcp): align answer and Asset behavior by kl3inIT · Pull Request #368 · kl3inIT/OrgMemory

kl3inIT · 2026-08-15T18:10:48Z

Scope

add stable one-based source numbers and direct-answer guidance to search_knowledge
keep released Asset instructions below host system, developer, safety, and tool-permission policy
treat Skill allowedTools as compatibility metadata rather than a permission grant
preserve opaque accessGap behavior and require explicit user intent before Asset execution or installation
bound search_assets to 10 candidates by default and 20 maximum
keep released_prompt as a user-role task message
reconcile Assistant/MCP and Asset Registry specs and test matrices

Evidence

./gradlew.bat --no-daemon compileJava :apps:mcp:test
./gradlew.bat --no-daemon clean test
focused AssetDeliveryToolsTests and OrgMemoryMcpContextTests
py -3 scripts/check_docs.py
mechanical backend static-analysis floor
corepack pnpm release:check
git diff --check

UI approval

Not applicable. This PR changes MCP contracts, metadata, and server behavior only; it has no web or authentication UI paths.

Release and risk

release note: .tegami/mcp-answer-and-asset-behavior.md
authorization remains enforced by the canonical API and live actor permissions; natural-language host guidance is not treated as the security boundary
some MCP hosts cache server/tool metadata, so deployment verification must refresh tool discovery and use a new conversation

Summary by CodeRabbit

New Features
- Knowledge search results now include stable, numbered sources for easier citation.
- Asset searches apply safe default and maximum result limits.
- MCP guidance now clarifies evidence-based answers, authorization boundaries, and policy handling.
- Released prompts clearly distinguish user-selected instructions from host system and safety policies.
Bug Fixes
- Improved handling of unavailable evidence, restricted assets, sensitive information, and hidden access details.
- Preserved explicit values when rendering released prompts.

coderabbitai · 2026-08-15T18:10:57Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: fa89bd76-03aa-40a1-8f15-6d14a54f85c9

📥 Commits

Reviewing files that changed from the base of the PR and between af458be and ece9195.

⛔ Files ignored due to path filters (4)

docs/specs/domains/asset-registry.md is excluded by !docs/**
docs/specs/domains/assistant-and-mcp.md is excluded by !docs/**
docs/tests/domains/asset-registry.md is excluded by !docs/**
docs/tests/domains/assistant-and-mcp.md is excluded by !docs/**

📒 Files selected for processing (11)

.tegami/mcp-answer-and-asset-behavior.md
apps/mcp/src/main/java/com/orgmemory/mcp/AssetDeliveryTools.java
apps/mcp/src/main/java/com/orgmemory/mcp/KnowledgeSearchApiClient.java
apps/mcp/src/main/java/com/orgmemory/mcp/KnowledgeSearchTool.java
apps/mcp/src/main/java/com/orgmemory/mcp/McpValues.java
apps/mcp/src/main/java/com/orgmemory/mcp/ReleasedPromptAdapter.java
apps/mcp/src/main/resources/application.yml
apps/mcp/src/test/java/com/orgmemory/mcp/AssetDeliveryToolsTests.java
apps/mcp/src/test/java/com/orgmemory/mcp/KnowledgeSearchApiClientTests.java
apps/mcp/src/test/java/com/orgmemory/mcp/KnowledgeSearchToolTests.java
apps/mcp/src/test/java/com/orgmemory/mcp/OrgMemoryMcpContextTests.java

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (2)

**/*

📄 CodeRabbit inference engine (AGENTS.md)

**/*: Always read this map and the relevant sections of ARCHITECTURE.md.
Do not use completed increment documents to answer what the system does now.
The repository, not chat or Northstar, is the engineering system of record.

Files:

apps/mcp/src/main/java/com/orgmemory/mcp/McpValues.java
apps/mcp/src/main/java/com/orgmemory/mcp/ReleasedPromptAdapter.java
apps/mcp/src/test/java/com/orgmemory/mcp/KnowledgeSearchToolTests.java
apps/mcp/src/main/resources/application.yml
apps/mcp/src/main/java/com/orgmemory/mcp/KnowledgeSearchTool.java
apps/mcp/src/test/java/com/orgmemory/mcp/AssetDeliveryToolsTests.java
apps/mcp/src/test/java/com/orgmemory/mcp/KnowledgeSearchApiClientTests.java
apps/mcp/src/test/java/com/orgmemory/mcp/OrgMemoryMcpContextTests.java
apps/mcp/src/main/java/com/orgmemory/mcp/AssetDeliveryTools.java
apps/mcp/src/main/java/com/orgmemory/mcp/KnowledgeSearchApiClient.java

**/*.{yml,yaml,properties}

📄 CodeRabbit inference engine (AGENTS.md)

Keep ddl-auto=validate and pair persisted-model changes with Flyway.

Files:

apps/mcp/src/main/resources/application.yml

🧠 Learnings (4)

📚 Learning: 2026-07-26T05:46:47.443Z

Learnt from: kl3inIT
Repo: kl3inIT/OrgMemory PR: 61
File: apps/mcp/src/main/java/com/orgmemory/mcp/McpSecurityConfiguration.java:50-52
Timestamp: 2026-07-26T05:46:47.443Z
Learning: In OrgMemory, treat the `apps/mcp` and `apps/api` as independent protocol adapter modules. When adjusting OAuth/wire-level scopes, do not introduce a shared Java constant or create a code dependency from `apps/mcp` to `apps/api` solely to deduplicate scope values. Instead, keep OAuth/scope constants adapter-local (e.g., in the relevant adapter/security configuration classes) and ensure cross-adapter consistency via automated realm/OAuth/authorization tests, rather than via shared wiring-level constants or cross-module references.

Applied to files:

apps/mcp/src/main/java/com/orgmemory/mcp/McpValues.java
apps/mcp/src/main/java/com/orgmemory/mcp/ReleasedPromptAdapter.java
apps/mcp/src/main/java/com/orgmemory/mcp/KnowledgeSearchTool.java
apps/mcp/src/main/java/com/orgmemory/mcp/AssetDeliveryTools.java
apps/mcp/src/main/java/com/orgmemory/mcp/KnowledgeSearchApiClient.java

📚 Learning: 2026-07-26T05:46:49.308Z

Learnt from: kl3inIT
Repo: kl3inIT/OrgMemory PR: 61
File: apps/mcp/src/main/java/com/orgmemory/mcp/McpTransportConfiguration.java:34-43
Timestamp: 2026-07-26T05:46:49.308Z
Learning: In the MCP module, authentication should be captured at servlet-time in `McpTransportConfiguration` (via the servlet `contextExtractor`) and stored in `McpTransportContext` under `AUTHENTICATION_CONTEXT_KEY`. Any authorization code (e.g., `McpApiAuthorization`) must consume this stored `Authentication` from `McpTransportContext` rather than re-reading it from `SecurityContextHolder`. Preserve the existing validation behavior: treat missing authentication as `null`, and only proceed when the consumed authentication is non-null and `authentication.isAuthenticated()` is true.

Applied to files:

apps/mcp/src/main/java/com/orgmemory/mcp/McpValues.java
apps/mcp/src/main/java/com/orgmemory/mcp/ReleasedPromptAdapter.java
apps/mcp/src/main/java/com/orgmemory/mcp/KnowledgeSearchTool.java
apps/mcp/src/main/java/com/orgmemory/mcp/AssetDeliveryTools.java
apps/mcp/src/main/java/com/orgmemory/mcp/KnowledgeSearchApiClient.java

📚 Learning: 2026-07-29T10:41:24.263Z

Learnt from: kl3inIT
Repo: kl3inIT/OrgMemory PR: 121
File: apps/mcp/src/main/java/com/orgmemory/mcp/AssetDeliveryResources.java:37-58
Timestamp: 2026-07-29T10:41:24.263Z
Learning: In the Java MCP module under apps/mcp, use Jackson 3 APIs consistently (e.g., tools.jackson.databind.ObjectMapper and tools.jackson.core.* exceptions). Jackson 3’s JacksonException hierarchy is unchecked (extends RuntimeException), so methods like ObjectMapper.writeValueAsString(...) do not require checked-exception handling (e.g., no try/catch or supplier wrapper just to satisfy checked exceptions). When reviewing this module, do not apply Jackson 2 (com.fasterxml.jackson) checked-exception catch/throws expectations to Jackson 3 call sites.

Applied to files:

apps/mcp/src/main/java/com/orgmemory/mcp/McpValues.java
apps/mcp/src/main/java/com/orgmemory/mcp/ReleasedPromptAdapter.java
apps/mcp/src/main/java/com/orgmemory/mcp/KnowledgeSearchTool.java
apps/mcp/src/main/java/com/orgmemory/mcp/AssetDeliveryTools.java
apps/mcp/src/main/java/com/orgmemory/mcp/KnowledgeSearchApiClient.java

📚 Learning: 2026-08-05T09:53:56.596Z

Learnt from: kl3inIT
Repo: kl3inIT/OrgMemory PR: 300
File: .tegami/2026-08-05-retrieval-recall-observations.md:7-7
Timestamp: 2026-08-05T09:53:56.596Z
Learning: For Tegami release fragments in `.tegami/*.md`, do not require a top-level H1 solely to satisfy markdownlint MD041. These fragments must instead contain an approved level-two public changelog section, such as `## Improvements`, as enforced by `scripts/check-release.mjs`; the generated release output contract prevents adding a second page-level H1.

Applied to files:

.tegami/mcp-answer-and-asset-behavior.md

🪛 ast-grep (0.45.1)

apps/mcp/src/test/java/com/orgmemory/mcp/AssetDeliveryToolsTests.java

[warning] 111-114: Avoid LDAP injections
Context: client.search(
"Bearer exchanged-api-token",
null,
null)
Note: [CWE-90] Improper Neutralization of Special Elements used in an LDAP Query ('LDAP Injection'). Security best practice.

(ldap-injection-java)

apps/mcp/src/main/java/com/orgmemory/mcp/AssetDeliveryTools.java

[warning] 58-59: Avoid LDAP injections
Context: assets.search(
authorization.require(context), query, type)
Note: [CWE-90] Improper Neutralization of Special Elements used in an LDAP Query ('LDAP Injection'). Security best practice.

(ldap-injection-java)

🪛 markdownlint-cli2 (0.23.2)

.tegami/mcp-answer-and-asset-behavior.md

[warning] 7-7: First line in a file should be a top-level heading

(MD041, first-line-heading, first-line-h1)

🔇 Additional comments (34)

apps/mcp/src/main/java/com/orgmemory/mcp/KnowledgeSearchApiClient.java (3)

4-4: LGTM!

48-52: LGTM!

56-104: LGTM!

apps/mcp/src/main/java/com/orgmemory/mcp/KnowledgeSearchTool.java (1)

26-29: LGTM!

apps/mcp/src/test/java/com/orgmemory/mcp/KnowledgeSearchApiClientTests.java (2)

72-77: LGTM!

79-115: LGTM!

apps/mcp/src/test/java/com/orgmemory/mcp/KnowledgeSearchToolTests.java (2)

5-5: LGTM!

62-65: LGTM!

apps/mcp/src/test/java/com/orgmemory/mcp/OrgMemoryMcpContextTests.java (5)

22-25: LGTM!

67-68: LGTM!

142-147: LGTM!

149-161: LGTM!

163-178: LGTM!

apps/mcp/src/main/java/com/orgmemory/mcp/McpValues.java (1)

14-25: LGTM!

apps/mcp/src/main/java/com/orgmemory/mcp/AssetDeliveryTools.java (10)

15-17: LGTM!

31-33: LGTM!

48-66: LGTM!

68-74: LGTM!

92-93: LGTM!

112-114: LGTM!

138-140: LGTM!

169-170: LGTM!

190-191: LGTM!

210-213: LGTM!

apps/mcp/src/test/java/com/orgmemory/mcp/AssetDeliveryToolsTests.java (6)

5-14: LGTM!

79-79: LGTM!

93-128: LGTM!

157-186: LGTM!

212-212: LGTM!

225-236: LGTM!

apps/mcp/src/main/java/com/orgmemory/mcp/ReleasedPromptAdapter.java (2)

45-47: LGTM!

70-76: LGTM!

apps/mcp/src/main/resources/application.yml (1)

42-57: LGTM!

.tegami/mcp-answer-and-asset-behavior.md (1)

1-14: LGTM!

📝 Walkthrough

Walkthrough

MCP knowledge searches now return stable source numbers. Asset searches enforce bounded limits. Tool descriptions, server instructions, and rendered prompts define authorization, policy precedence, citation, disclosure, and access-gap behavior.

Changes

MCP behavior

Layer / File(s)	Summary
Stable knowledge evidence `apps/mcp/src/main/java/com/orgmemory/mcp/KnowledgeSearchApiClient.java`, `apps/mcp/src/main/java/com/orgmemory/mcp/KnowledgeSearchTool.java`, `apps/mcp/src/test/java/com/orgmemory/mcp/KnowledgeSearchApiClientTests.java`, `apps/mcp/src/test/java/com/orgmemory/mcp/KnowledgeSearchToolTests.java`, `apps/mcp/src/test/java/com/orgmemory/mcp/OrgMemoryMcpContextTests.java`	Search evidence receives immutable one-based source numbers. Tool guidance covers ordered evidence, bracketed citations, response language, and limited access metadata.
Bounded asset discovery `apps/mcp/src/main/java/com/orgmemory/mcp/McpValues.java`, `apps/mcp/src/main/java/com/orgmemory/mcp/AssetDeliveryTools.java`, `apps/mcp/src/test/java/com/orgmemory/mcp/AssetDeliveryToolsTests.java`	Asset search uses a default limit of 10 and rejects limits above 20. Results are bounded candidates.
Asset policy and prompt rendering `apps/mcp/src/main/java/com/orgmemory/mcp/AssetDeliveryTools.java`, `apps/mcp/src/main/java/com/orgmemory/mcp/ReleasedPromptAdapter.java`, `apps/mcp/src/main/resources/application.yml`, `apps/mcp/src/test/java/com/orgmemory/mcp/AssetDeliveryToolsTests.java`, `apps/mcp/src/test/java/com/orgmemory/mcp/OrgMemoryMcpContextTests.java`, `.tegami/mcp-answer-and-asset-behavior.md`	Asset content and Skill metadata cannot override host policies or grant authorization. Access gaps remain opaque. Released prompts render as user-role task input, and server instructions require evidence-only answers and explicit asset actions.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to ece91

The PR updates MCP answer and Asset behavior with bounded search results and explicit execution guidance; no actionable merge-blocking risk remains beyond normal checks and review.

Possibly related PRs

kl3inIT/OrgMemory#60: Modified the same MCP asset and prompt behavior.
kl3inIT/OrgMemory#61: Changed the same MCP asset, search, prompt, and instruction components.
kl3inIT/OrgMemory#65: Introduced the structured asset search output refined by this change.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the MCP answer and Asset behavior changes.
Description check	✅ Passed	The description covers the change scope, validation evidence, documentation impact, release note, and risk information.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch fix/mcp-answer-guidance

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

kl3inIT · 2026-08-15T18:11:08Z

@coderabbitai review

coderabbitai · 2026-08-15T18:11:13Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

github-actions · 2026-08-15T18:11:54Z

Tegami

This repository uses Tegami to manage releases. When your changes affect published packages, add a changelog file under .tegami/ before merging.

Create a changelog → · Changelog format

Release preview

Package	Bump	Version
`orgmemory`	minor	`0.5.0` → `0.6.0`

Changelogs in this PR

Changelog	Title
`mcp-answer-and-asset-behavior.md`	Fixes

Run pnpm run tegami locally to create a changelog interactively.

_{Managed by Tegami.}

kl3inIT added 5 commits August 16, 2026 00:51

fix(mcp): align knowledge answer guidance

9fd9388

docs(mcp): document answer guidance contract

2993bb6

fix(mcp): harden released Asset behavior

a8eec46

docs(mcp): reconcile Asset behavior boundary

45faaf4

docs(release): note MCP behavior hardening

ece9195

kl3inIT merged commit db999fa into main Aug 15, 2026
19 checks passed

kl3inIT deleted the fix/mcp-answer-guidance branch August 15, 2026 18:13

Navigation Menu

fix(mcp): align answer and Asset behavior - #368

fix(mcp): align answer and Asset behavior#368
kl3inIT merged 5 commits into
mainfrom
fix/mcp-answer-guidance

kl3inIT commented Aug 15, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Aug 15, 2026 •

edited

Loading

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

kl3inIT commented Aug 15, 2026

Uh oh!

coderabbitai Bot commented Aug 15, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

kl3inIT commented Aug 15, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Scope

Evidence

UI approval

Release and risk

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Aug 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

kl3inIT commented Aug 15, 2026

Uh oh!

coderabbitai Bot commented Aug 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 15, 2026

Tegami

Release preview

Changelogs in this PR

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

kl3inIT commented Aug 15, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Aug 15, 2026 •

edited

Loading

coderabbitai Bot commented Aug 15, 2026 •

edited

Loading