forgejo_admin/pal-e-mcp
1
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions

6d: Add semantic_search MCP tool #29

New issue
Closed
opened 2026-03-09 14:33:26 +00:00 by forgejo_admin · 1 comment
forgejo_admin commented 2026-03-09 14:33:26 +00:00
Owner
Copy link

Lineage

plan-2026-02-26-tf-modularize-postgres → Phase 6 (Vector Search) → Phase 6d (Semantic Search) → Deliverable 3 (MCP)

Repo

forgejo_admin/pal-e-docs-mcp

User Story

As an AI agent using Claude Code
I want a semantic_search MCP tool
So that I can find related knowledge by meaning directly from my tool context

Context

PR #138 on pal-e-docs added GET /notes/semantic-search. PR #20 on pal-e-docs-sdk added client.semantic_search(). This issue adds the MCP tool wrapper.

The search_notes tool in src/pal_e_docs_mcp/tools/notes.py (lines 50-84) is the exact pattern to copy.

File Targets

Files to modify:

  • src/pal_e_docs_mcp/tools/notes.py — add semantic_search tool (copy search_notes pattern, call get_sdk().semantic_search())

Files to create:

  • Tests if a test file exists for tools — add test for the new tool

Files to reference (don't modify):

  • src/pal_e_docs_mcp/server.py — server setup, SDK initialization

Acceptance Criteria

  • semantic_search tool registered and callable
  • Parameters: query (required), limit, note_type, project, tags, status
  • Calls get_sdk().semantic_search(query, ...)
  • Returns JSON string via _ok() helper on success
  • Returns error via _error_response() on failure
  • Tool docstring describes what it does and what fields are returned

Test Expectations

  • If tests exist, add test for new tool
  • Run command: check if tests exist first, run them if so

Constraints

  • Copy the search_notes tool pattern exactly — same decorator, same parameter annotations, same error handling
  • Do NOT add new dependencies
  • Do NOT change server.py
  • This is ~30 lines of code — keep it simple

Checklist

  • PR opened
  • Tests pass (if they exist)
  • No unrelated changes
  • PR description includes Closes #N

Related

  • phase-postgres-6d-semantic-search — phase note
  • PR #20 (pal-e-docs-sdk) — the SDK method this wraps
  • PR #138 (pal-e-docs) — the API endpoint
### Lineage `plan-2026-02-26-tf-modularize-postgres` → Phase 6 (Vector Search) → Phase 6d (Semantic Search) → Deliverable 3 (MCP) ### Repo `forgejo_admin/pal-e-docs-mcp` ### User Story As an AI agent using Claude Code I want a `semantic_search` MCP tool So that I can find related knowledge by meaning directly from my tool context ### Context PR #138 on pal-e-docs added `GET /notes/semantic-search`. PR #20 on pal-e-docs-sdk added `client.semantic_search()`. This issue adds the MCP tool wrapper. The `search_notes` tool in `src/pal_e_docs_mcp/tools/notes.py` (lines 50-84) is the **exact pattern** to copy. ### File Targets Files to modify: - `src/pal_e_docs_mcp/tools/notes.py` — add `semantic_search` tool (copy `search_notes` pattern, call `get_sdk().semantic_search()`) Files to create: - Tests if a test file exists for tools — add test for the new tool Files to reference (don't modify): - `src/pal_e_docs_mcp/server.py` — server setup, SDK initialization ### Acceptance Criteria - [ ] `semantic_search` tool registered and callable - [ ] Parameters: `query` (required), `limit`, `note_type`, `project`, `tags`, `status` - [ ] Calls `get_sdk().semantic_search(query, ...)` - [ ] Returns JSON string via `_ok()` helper on success - [ ] Returns error via `_error_response()` on failure - [ ] Tool docstring describes what it does and what fields are returned ### Test Expectations - [ ] If tests exist, add test for new tool - Run command: check if tests exist first, run them if so ### Constraints - Copy the `search_notes` tool pattern exactly — same decorator, same parameter annotations, same error handling - Do NOT add new dependencies - Do NOT change server.py - This is ~30 lines of code — keep it simple ### Checklist - [ ] PR opened - [ ] Tests pass (if they exist) - [ ] No unrelated changes - [ ] PR description includes `Closes #N` ### Related - `phase-postgres-6d-semantic-search` — phase note - PR #20 (pal-e-docs-sdk) — the SDK method this wraps - PR #138 (pal-e-docs) — the API endpoint
forgejo_admin commented 2026-03-09 14:38:42 +00:00
Author
Owner
Copy link

PR #30 Review

BLOCKERS

1. pyproject.toml SDK version constraint not bumped (line 14)

The dependency is still pal-e-docs-sdk>=0.1.0, but the new semantic_search tool calls get_sdk().semantic_search() -- a method that only exists in SDK 0.2.0+. If the dependency resolver picks 0.1.0 (which the constraint allows), the tool crashes at runtime with AttributeError.

Fix: bump to pal-e-docs-sdk>=0.2.0 in pyproject.toml.

File: /home/ldraney/pal-e-docs-mcp/pyproject.toml, line 14.

NITS

None. The implementation is a clean, minimal copy of the search_notes pattern.

SOP COMPLIANCE

  • Branch named after issue (29-add-semantic-search-mcp-tool references #29)
  • PR body has: Summary, Changes, Test Plan, Related
  • Related references the plan slug (plan-2026-02-26-tf-modularize-postgres)
  • Closes #29 present in PR body
  • No secrets, .env files, or credentials committed
  • No unrelated changes (3 files, all in scope)
  • Tests added (4 new tests in TestSemanticSearch, total 43 passing)

CODE REVIEW

Tool implementation (notes.py lines 87-122): Near-exact copy of search_notes. Decorator, parameter annotations, docstring, try/except, _ok/_error_response -- all match. Positional query arg forwarded correctly to SDK. All 6 parameters present and in the same order as search_notes.

Tests (test_param_alignment.py lines 128-166): Four tests cover the key boundary behaviors -- positional arg mapping, optional filter forwarding, defaults-to-none, and error response formatting. Mirrors the existing TestSearchNotes pattern but with fuller coverage.

SDK bump (uv.lock): Correctly bumped from 0.1.0 to 0.2.0 with updated hashes. However, pyproject.toml was missed (see BLOCKER above).

Registration: No changes needed to __init__.py since semantic_search is defined in notes.py which is already imported by register_all_tools().

VERDICT: NOT APPROVED

One blocker: pyproject.toml must bump the SDK floor to >=0.2.0 to match the runtime requirement. Everything else is solid.

## PR #30 Review ### BLOCKERS **1. `pyproject.toml` SDK version constraint not bumped (line 14)** The dependency is still `pal-e-docs-sdk>=0.1.0`, but the new `semantic_search` tool calls `get_sdk().semantic_search()` -- a method that only exists in SDK 0.2.0+. If the dependency resolver picks 0.1.0 (which the constraint allows), the tool crashes at runtime with `AttributeError`. Fix: bump to `pal-e-docs-sdk>=0.2.0` in `pyproject.toml`. File: `/home/ldraney/pal-e-docs-mcp/pyproject.toml`, line 14. ### NITS None. The implementation is a clean, minimal copy of the `search_notes` pattern. ### SOP COMPLIANCE - [x] Branch named after issue (`29-add-semantic-search-mcp-tool` references #29) - [x] PR body has: Summary, Changes, Test Plan, Related - [x] Related references the plan slug (`plan-2026-02-26-tf-modularize-postgres`) - [x] `Closes #29` present in PR body - [x] No secrets, `.env` files, or credentials committed - [x] No unrelated changes (3 files, all in scope) - [x] Tests added (4 new tests in `TestSemanticSearch`, total 43 passing) ### CODE REVIEW **Tool implementation** (`notes.py` lines 87-122): Near-exact copy of `search_notes`. Decorator, parameter annotations, docstring, try/except, `_ok`/`_error_response` -- all match. Positional `query` arg forwarded correctly to SDK. All 6 parameters present and in the same order as `search_notes`. **Tests** (`test_param_alignment.py` lines 128-166): Four tests cover the key boundary behaviors -- positional arg mapping, optional filter forwarding, defaults-to-none, and error response formatting. Mirrors the existing `TestSearchNotes` pattern but with fuller coverage. **SDK bump** (`uv.lock`): Correctly bumped from 0.1.0 to 0.2.0 with updated hashes. However, `pyproject.toml` was missed (see BLOCKER above). **Registration**: No changes needed to `__init__.py` since `semantic_search` is defined in `notes.py` which is already imported by `register_all_tools()`. ### VERDICT: NOT APPROVED One blocker: `pyproject.toml` must bump the SDK floor to `>=0.2.0` to match the runtime requirement. Everything else is solid.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels   
domain:backend

   
domain:devops

   
domain:frontend

   
status:approved

QA passed, awaiting merge approval

  
status:in-progress

Dev agent is actively working

  
status:needs-fix

QA found issues, back to dev

  
status:qa

PR submitted, awaiting QA review

  
type:bug

Bug fix

  
type:devops

Infrastructure/CI/config work

  
type:feature

New functionality

No labels
domain:backend
domain:devops
domain:frontend
status:approved
status:in-progress
status:needs-fix
status:qa
type:bug
type:devops
type:feature
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
forgejo_admin/pal-e-mcp#29
No description provided.