cardosofelipe/syndarix
1
0
Fork 0
forked from cardosofelipe/fast-next-template
Code Issues 18 Pull Requests Wiki Activity

feat(knowledge-base): implement Knowledge Base MCP Server (#57) #72

Closed
cardosofelipe wants to merge 0 commits from feature/57-knowledge-base-mcp-server into dev
pull from: feature/57-knowledge-base-mcp-server
merge into: cardosofelipe:dev
Conversation 0 Commits - Files Changed -
cardosofelipe commented 2026-01-03 20:33:51 +00:00
Owner
Copy Link

Summary

Implements the Knowledge Base MCP Server providing RAG capabilities with pgvector for semantic search, intelligent chunking, and collection management.

Features

  • Intelligent Chunking: Code-aware (Python, JS, TS, Go, Rust), markdown-aware (respects heading hierarchy), and text-based chunking strategies
  • Semantic Search: Vector similarity search using pgvector with HNSW indexing
  • Keyword Search: PostgreSQL full-text search with ts_rank scoring
  • Hybrid Search: Combines semantic + keyword using Reciprocal Rank Fusion (RRF)
  • Redis Caching: Deduplicates embedding generation requests
  • Collection Management: Organize knowledge into named collections per project

MCP Tools

  1. search_knowledge - Search with semantic, keyword, or hybrid modes
  2. ingest_content - Add content with automatic chunking and embedding
  3. delete_content - Remove by source path, collection, or chunk IDs
  4. list_collections - List all collections in a project
  5. get_collection_stats - Detailed statistics for a collection
  6. update_document - Replace existing document content

Architecture

  • Database: PostgreSQL with pgvector extension (1536-dim HNSW index)
  • Cache: Redis for embedding deduplication
  • Embeddings: Via LLM Gateway MCP server
  • Tokenization: tiktoken (cl100k_base)

Testing

  • 128 comprehensive tests covering all components
  • 58% code coverage (database tests use mocks, not live DB)
  • Passes ruff linting and mypy type checking

Test plan

  • All 128 unit tests passing
  • Ruff linting passes
  • Mypy type checking passes
  • Multi-agent code review completed (code quality, security, architecture, test coverage)
  • Manual testing with live PostgreSQL and Redis (requires infrastructure)

Related Issues

Closes #57

Generated with Claude Code

## Summary Implements the Knowledge Base MCP Server providing RAG capabilities with pgvector for semantic search, intelligent chunking, and collection management. ### Features - **Intelligent Chunking**: Code-aware (Python, JS, TS, Go, Rust), markdown-aware (respects heading hierarchy), and text-based chunking strategies - **Semantic Search**: Vector similarity search using pgvector with HNSW indexing - **Keyword Search**: PostgreSQL full-text search with ts_rank scoring - **Hybrid Search**: Combines semantic + keyword using Reciprocal Rank Fusion (RRF) - **Redis Caching**: Deduplicates embedding generation requests - **Collection Management**: Organize knowledge into named collections per project ### MCP Tools 1. `search_knowledge` - Search with semantic, keyword, or hybrid modes 2. `ingest_content` - Add content with automatic chunking and embedding 3. `delete_content` - Remove by source path, collection, or chunk IDs 4. `list_collections` - List all collections in a project 5. `get_collection_stats` - Detailed statistics for a collection 6. `update_document` - Replace existing document content ### Architecture - Database: PostgreSQL with pgvector extension (1536-dim HNSW index) - Cache: Redis for embedding deduplication - Embeddings: Via LLM Gateway MCP server - Tokenization: tiktoken (cl100k_base) ### Testing - 128 comprehensive tests covering all components - 58% code coverage (database tests use mocks, not live DB) - Passes ruff linting and mypy type checking ## Test plan - [x] All 128 unit tests passing - [x] Ruff linting passes - [x] Mypy type checking passes - [x] Multi-agent code review completed (code quality, security, architecture, test coverage) - [ ] Manual testing with live PostgreSQL and Redis (requires infrastructure) ## Related Issues Closes #57 --- Generated with [Claude Code](https://claude.com/claude-code)
cardosofelipe added 1 commit 2026-01-03 20:33:51 +00:00
feat(knowledge-base): implement Knowledge Base MCP Server (#57) d0fc7f37ff 
Implements RAG capabilities with pgvector for semantic search:

- Intelligent chunking strategies (code-aware, markdown-aware, text)
- Semantic search with vector similarity (HNSW index)
- Keyword search with PostgreSQL full-text search
- Hybrid search using Reciprocal Rank Fusion (RRF)
- Redis caching for embeddings
- Collection management (ingest, search, delete, stats)
- FastMCP tools: search_knowledge, ingest_content, delete_content,
  list_collections, get_collection_stats, update_document

Testing:
- 128 comprehensive tests covering all components
- 58% code coverage (database integration tests use mocks)
- Passes ruff linting and mypy type checking

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
cardosofelipe added 4 commits 2026-01-04 00:08:59 +00:00
refactor(environment): update virtualenv path to /opt/venv in Docker setup ca5f5e3383 
- Adjusted `docker-compose.dev.yml` to reflect the new venv location.
- Modified entrypoint script and Dockerfile to reference `/opt/venv` for isolated dependencies.
- Improved bind mount setup to prevent venv overwrites during development.
docs(workflow): enforce stack verification as mandatory step e6e98d4ed1 
- Added "Stack Verification" section to CLAUDE.md with detailed steps.
- Updated WORKFLOW.md to mandate running the full stack before marking work as complete.
- Prevents issues where high test coverage masks application startup failures.
fix(mcp-kb): address critical issues from deep review 953af52d0e 
- Fix SQL HAVING clause bug by using CTE approach (closes #73)
- Add /mcp JSON-RPC 2.0 endpoint for tool execution (closes #74)
- Add /mcp/tools endpoint for tool discovery (closes #75)
- Add content size limits to prevent DoS attacks (closes #78)
- Add comprehensive tests for new endpoints

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
fix(mcp-kb): add transactional batch insert and atomic document update cd7a9ccbdf 
- Wrap store_embeddings_batch in transaction for all-or-nothing semantics
- Add replace_source_embeddings method for atomic document updates
- Update collection_manager to use transactional replace
- Prevents race conditions and data inconsistency (closes #77)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
cardosofelipe added 1 commit 2026-01-04 00:20:03 +00:00
fix(mcp-kb): add input validation, path security, and health checks 6bb376a336 
Security fixes from deep review:
- Add input validation patterns for project_id, agent_id, collection
- Add path traversal protection for source_path (reject .., null bytes)
- Add error codes (INTERNAL_ERROR) to generic exception handlers
- Handle FieldInfo objects in validation for test robustness

Performance fixes:
- Enable concurrent hybrid search with asyncio.gather

Health endpoint improvements:
- Check all dependencies (database, Redis, LLM Gateway)
- Return degraded/unhealthy status based on dependency health
- Updated tests for new health check response structure

All 139 tests pass.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
cardosofelipe closed this pull request 2026-01-04 18:48:33 +00:00
cardosofelipe deleted branch feature/57-knowledge-base-mcp-server 2026-01-04 18:48:33 +00:00

Pull request closed

This pull request cannot be reopened because the branch was deleted.
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
agents
Agent orchestration
 architecture
Architectural decisions
 backend
Backend work
 blocked
Blocked by dependency
 database
Database/migrations
 design
UI/UX design work
 devops
DevOps/Infrastructure work
 epic
Epic/parent issue
 frontend
Frontend work
 infrastructure
Infrastructure / DevOps
 mcp
MCP related
 phase-0
Phase 0: Foundation
 phase-1
Phase 1: Core Platform
 phase-2
Phase 2: MCP Integration
 priority:high
High priority
 spike
Architecture spike / research task
No Label
Milestone
No items
No Milestone
Assignees
Clear assignees
cardosofelipe
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: cardosofelipe/syndarix#72
Delete Branch "feature/57-knowledge-base-mcp-server"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?