[Feature] Improve MCP architecture for multi-repo and multi-session support

[hashtafak]

Describe the Issue

repowise's MCP server architecture is fundamentally single-tenant - one MCP server process per repository - which creates several limitations for multi-repo and multi-user workflows.

Steps to Reproduce

1. Open multiple IDEs/CLIs accessing different repositories
2. Each requires its own MCP server process: repowise mcp /path/to/repo1
3. For SSE transport, each needs unique port: repowise mcp --transport sse --port 7338
4. Try concurrent generation operations on the same repository
5. Observe SQLite database locking and port conflicts

Current Limitations

No Centralized MCP Server

• Each repository requires its own MCP server process
• Server uses module-level globals tied to one repository path
• MCP config generation creates repository-specific configurations

SQLite Database Locking

• Multiple MCP servers accessing the same SQLite database experience locking during write operations
• SQLite allows multiple readers but only one writer at a time
• Generation operations involve both reads and writes, causing blocking for concurrent processes

SSE Transport Port Management

• SSE transport requires unique ports per repository (default: 7338)
• Creates configuration overhead for multi-repo workflows
• Each client needs repository-specific port settings

No Multi-CLI Session Support

• Architecture prioritizes single-user workflows over multi-session coordination
• No centralized session broker or lock management for generation operations
• Resource contention on vector stores and search indices

Expected Behavior

• Single MCP server should be able to serve multiple repositories
• Multiple CLI/IDE instances should access the same repository without conflicts
• SSE transport should not require manual port management per repository
• Generation operations should handle concurrent access gracefully

Proposed Solution

1. Centralized session broker to coordinate multiple MCP connections
2. Shared vector store with concurrent access patterns
3. Lock management for generation operations

Current Workarounds

1. Use stdio transport for IDE integration (avoids port conflicts)
2. Hosted version for team environments with cross-repo intelligence
3. Port allocation strategy for SSE transport (reserve port ranges)

Environment

• OS: Windows 10
• Python version: 3.14
• Repowise version: 0.3.0
• Installation method: pip

Additional Context

The current design prioritizes simplicity and single-user workflows. For team environments requiring multi-repo intelligence, architectural improvements are needed to support:

• Multiple developers working on the same repository simultaneously
• Single MCP server serving multiple repositories
• Web-based clients without port management overhead
• Concurrent generation operations without database locking

This would make repowise more suitable for team environments and complex multi-repo workflows.
Achieve the same results as oraios/serena mcp.

• Deepwiki

[RaghavChamadiya]

Thanks for the detailed framing. This is a real gap and the workarounds you've identified (stdio for IDE, port allocation for SSE, hosted version for teams) are correct.

To set expectations: this is a multi-week refactor that touches the MCP transport layer, the SQLite write path, and the session/connection lifecycle, so it's a roadmap-level item rather than something we'll land soon. Tagging it for v0.4 planning.

A few smaller pieces could be cherry-picked sooner without the full architectural change, and these would unblock most real-world multi-process pain:

1. SQLite WAL + busy_timeout — addresses the database locked errors you described and the ones in OperationalError: database is locked on concurrent repowise update #95. Coarse-grained but it makes concurrent reads safe and gives writers a polite back-off instead of immediate failure. Going to fix this separately.
2. Workspace-level lock file for repowise update so a second invocation either waits or fails fast with a clear message instead of a raw OperationalError. Also a small change.
3. Port auto-discovery for SSE transport so the MCP server picks the next free port and writes it to the workspace state, instead of requiring users to coordinate ports manually.

The full multi-tenant MCP server architecture is a bigger discussion — happy to spec it out in this issue or move it to a design doc if anyone wants to prototype. Leaving open as the tracking issue.

[Leeaandrob]

I would love to help make it possible @RaghavChamadiya. My suggestion is not use SSE and use HTTP Transport as well.

[RaghavChamadiya]

@
@Leeaandrob appreciate the offer, would genuinely welcome the help.

You are right on HTTP, the move away from SSE is the right direction regardless of the multi-tenant work. Worth doing as its own focused PR rather than bundling it into the bigger architecture change.

Concrete entry points if you want to take it on:

• CLI flag lives at packages/cli/src/repowise/cli/commands/mcp_cmd.py:14-16, currently a click.Choice(["stdio", "sse"]) with stdio as default
• Dispatch is at packages/server/src/repowise/server/mcp_server/_server.py:329-341, a clean if/else that calls FastMCP.run(transport=...)
• Both transports go through FastMCP, not through the lower level mcp.server.sse or mcp.server.streamable_http modules directly, so part of this work is checking what our pinned MCP SDK version supports for streamable HTTP and bumping if needed

Adding the option itself is a one line Choice extension and one extra branch. The interesting part is the SDK version question and whether we keep SSE around for one release as a deprecation path.

Two other small targets if HTTP transport feels tangled, both contained:

• The single repo MCP server path in _server.py:264-269 builds its async engine via create_async_engine directly and bypasses our pragma listener in packages/core/src/repowise/core/persistence/database.py, so it runs without WAL or busy_timeout. Routing it through the projects engine factory would close that gap.
• No lock file exists around repowise update anywhere in packages/cli. A simple file lock that either waits or fails fast with a clear message would replace the raw OperationalError users see today.

Ping me on whichever you pick and I will make time to review.
@