* feat(mcp): add built-in MCP server with per-workspace endpoints
WeKnora previously exposed itself to MCP clients only through the Python
package under mcp-server/, which binds one process to one API key and
therefore to one workspace, and mirrors the REST API tool-for-tool.
This adds a native MCP server surface to the Go backend:
- New mcp_endpoints table (PostgreSQL 000100, SQLite 000020). A workspace
can publish any number of endpoints, each with its own bearer token
(SHA-256 stored, rotatable, shown once), knowledge-base allowlist, tool
allowlist, default agent and per-minute rate limit.
- Management API under /api/v1/mcp-endpoints (Viewer reads, Admin writes,
API keys need manage_channels) plus a tool catalog endpoint.
- internal/mcpserver hosts one mcp-go Streamable HTTP server in stateless
mode at /mcp/:endpoint_id. tools/list is filtered per endpoint and
tools/call re-checks the allowlist, applies rate limiting and touches
last_used_at. MCPEndpointAuth resolves the token and injects the
workspace, an mcp_endpoint principal and an API-key style scope derived
from the endpoint, so existing knowledge-base and capability checks
apply unchanged.
- Redesigned tool set (12 tools in four groups): retrieval and reading
reuse the agent's native tools; ask runs the default or a named agent
synchronously and returns a cited answer with a session_id for
follow-ups; wiki tools cover search, read and index; write tools are
off by default. Knowledge bases accept ids or names.
- Frontend: new "MCP Server" integrations tab (tab id mcpserver, to
avoid clashing with the existing MCP-client settings section) with
endpoint cards, a create/edit drawer, a one-time token dialog and
ready-to-paste snippets for Cursor/VS Code/Claude Desktop, Claude Code
and mcp-remote. Locales updated in all five languages.
- Deployment capability integrations.mcpserver wired on both sides.
- Docs: website-docs MCP page now leads with the built-in server; the
Python mcp-server README carries a deprecation notice.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* fix(mcp): wire the MCP server into DI/router and tighten authorization
The previous commit lost eight staged files to the repo pre-commit hook,
which resolves ROOT to the main checkout and re-adds the main-checkout
copies of tracked files into the worktree index. This commit restores them
(container providers, RouterParams and route registration, context key,
principal, clone table entry, deployment capability key, SQLite parity
test) and addresses the review findings:
- Knowledge-base scope is authorized, not trusted: endpoint allowlists and
every tool call resolve each knowledge base through access.ResolveKB for
the calling principal (ownership or organization share). Foreign IDs are
rejected on create/update and dropped at call time.
- Write tools mint explicit editor grants via access.KBAccess.WithGrant
before calling the knowledge service, so add/update/delete go through the
same RequireKBWrite path as the REST API. add_document also checks the
grant itself.
- ask no longer accepts agent_id. It runs only the endpoint's configured
agent; tenant-owned agents and user-facing builtins qualify, internal
builtins (wiki fixer, skill installer) are refused both on save and at
call time. Web search is forced off for MCP calls.
- Tool annotations match behaviour: ask is not read-only, add_document is
a mutation.
- CORS allows MCP-Protocol-Version / Mcp-Session-Id / Last-Event-ID and
exposes Mcp-Session-Id for browser-based MCP clients.
- Rate limiter runs its local cleanup goroutine; SQLite migration gains the
deleted_at index for parity with PostgreSQL; non-ASCII endpoint names get
unique mcpServers keys derived from the endpoint id.
- Swagger annotations on the management handler.
- Tests: KB isolation (service and server), write grants, endpoint-agent
restriction, tool annotations, and a router test that mounts the public
/mcp/:endpoint_id surface and checks the deployment capability.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* chore(mcp): renumber migrations after rebase onto main
main took 000100 / 000020 for chunks_index_diet, so the mcp_endpoints
migrations move to 000101 (PostgreSQL) and 000021 (SQLite); the SQLite
parity test and docs follow.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* fix(mcp): run document tools under the knowledge base owner tenant
Shared knowledge bases resolved through access.ResolveKB were only half
usable: documents of an organization-shared knowledge base are stored under
the owner tenant, so the document-level tools that queried by the calling
tenant found nothing, and add_document would have created rows under the
caller's tenant inside someone else's knowledge base.
- knowledgeInScope loads documents tenant-agnostically and then requires
the document to belong to an allowed knowledge base and to that base's
tenant.
- scopedKBContext replaces grantContext: it resolves the grant, switches
the execution tenant to the knowledge base owner (KBAccess.Context) and
swaps TenantInfo to the owner so storage/model settings resolve there.
list_documents, read_document and every write tool run under it.
- Locale text and docs no longer claim clients can pass agent_id.
- Go SDK gains MCP endpoint methods (client/mcp_endpoint.go) with docs, and
the Swagger artifacts are regenerated.
- Tests: shared knowledge base read/write under the owner tenant, spoofed
document tenant rejected, viewer share cannot write.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* chore(mcp): renumber migrations after rebase onto main
main now carries 000101 / 000021 (knowledge_profiles), so the
mcp_endpoints migrations move to 000102 (PostgreSQL) and 000022 (SQLite);
the SQLite parity test expects version 22 and the docs follow.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* fix(mcp): guard last_used touch without a repository and wrap SDK line
The transport tests build the server without a repository; the background
last_used_at write then dereferenced a nil interface and, on the slower CI
runner, took the test binary down. touchLastUsed now returns early when no
repository is wired, and the tests inject a recording repository and assert
the touch instead. Also wraps a 123-column SDK signature for the client
module's lll check.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
create_knowledge_from_file never sent fileName, so MCP uploads always
landed in the knowledge-base root even though the backend has accepted
path-qualified names (folder_path + display name) since v0.7.2.
list_knowledge also dropped folder_path / folder_scope query params that
the REST list endpoint already supports.
Fixes#3173
List create_knowledge_from_file (previously missing from the README tool
list) and the new create_knowledge_from_text in README.md and EXAMPLES.md,
and add a CHANGELOG entry under Unreleased.
Add an MCP tool that creates a knowledge entry from raw Markdown text by
calling the existing backend endpoint
POST /knowledge-bases/{id}/knowledge/manual (handler.CreateManualKnowledge).
This completes the "text" half of #323, whose "file" half was already
covered by create_knowledge_from_file.
The tool defaults to status="publish" so the created entry is chunked,
embedded and made searchable immediately — matching the API/MCP use case
where there is no UI to publish a draft. Callers may pass status="draft"
to save without indexing.
- New client method WeKnoraClient.create_knowledge_from_text.
- New @mcp.tool() create_knowledge_from_text, resolving kb_id by name or
UUID (consistent with create_session / hybrid_search).
- Add focused unittests verifying endpoint, request body shape, status
default/override, and kb_id resolution wiring.
- Bump the stdio tools-list count assertion in test_mcp_transports.py
from 29 to 30 for the newly registered tool.
GET /shared-knowledge-bases returns rows with nested knowledge_base
(sharedKBRow), unlike GET /knowledge-bases which returns flat KB objects.
resolve_kb_id and agent_chat preflight were reading top-level id/name,
so shared KB names never matched. Add _normalize_kb_entries and tests.
resolve_kb_id now searches both own and shared knowledge bases when
resolving a name to UUID. Error messages and docstrings in hybrid_search,
chat, and agent_chat now reference list_shared_knowledge_bases as well.
Co-Authored-By: Claude <noreply@anthropic.com>
Add a new MCP tool to list knowledge bases shared from other workspaces
via the GET /shared-knowledge-bases endpoint, which was previously not
exposed through the MCP server.
- Add WeKnoraClient.list_shared_knowledge_bases() method
- Register list_shared_knowledge_bases() as an @mcp.tool()
Co-Authored-By: Claude <noreply@anthropic.com>
Rename the distribution to tencent-weknora-mcp, point metadata at
Tencent/WeKnora, bump to 1.1.1 for the transport/session fixes, and
tighten publish to main/tags only via Trusted Publishing.
Keep stateless HTTP and /sse/messages/ paths aligned with pre-2.x behavior,
use thread-local requests.Session for concurrent tool handlers, and add
transport regression tests.
MCP Python SDK 2.0 removed the low-level Server decorator API
(@app.list_tools() / @app.call_tool() / app.get_capabilities()), so the
server crashed at startup with:
AttributeError: 'Server' object has no attribute 'list_tools'
The released PyPI package weknora-mcp==1.0.1 declared 'mcp>=1.0.0' with
no upper bound, so uvx resolved to the latest 2.0.0 and the plugin's
weknora MCP server could no longer connect.
Fix: rewrite the server on top of the mcp 2.x high-level MCPServer API
(formerly FastMCP), and cap the dependency at 'mcp>=2,<3'.
- weknora_mcp_server.py: replace @app.list_tools()/@app.call_tool() with
28 @mcp.tool() function-signature tools (input schema auto-generated
from type hints, descriptions from docstrings, plain return values
serialized by the framework). Transports use run_stdio_async() /
sse_app() / streamable_http_app(). WeKnoraClient business logic is
unchanged.
- deps: mcp>=2,<3 in pyproject.toml / requirements.txt / setup.py;
commit uv.lock pinning mcp 2.0.0.
- version bump to 1.1.0 (pyproject, setup, __init__, main --version,
server_version).
- check_imports.py: validate MCPServer / ToolError / mcp_types imports.
- ci(.github/workflows/mcp-server.yml): publish on merge to main +
manual dispatch, not only on tags; add PyPI version-dedup check so
re-runs on an unchanged version stay green (absorbed from PR #2399).
Verified: stdio initialize + tools/list returns all 28 tools; no
list_tools AttributeError; tool dispatch + error wrapping confirmed.
Co-authored-by: wizardchen <wizardchen@tencent.com>
Convert test_module.py to unittest.TestCase so mcp-server.yml's
unittest discover picks up integration checks. Rename test_imports.py
to check_imports.py to keep manual diagnostics out of discovery.
WeKnora MCP Server still uses v1 low-level Server decorators such as
@app.list_tools(). MCP SDK 2.0 removed those APIs, so fresh installs
could fail at startup with AttributeError. Cap the dependency at <2 and
require >=1.28 for Streamable HTTP transport support.
* fix(mcp-server): route diagnostics to stderr to fix stdio protocol crash
Entry scripts (run_server.py, main.py, run.py) printed diagnostics to
stdout via bare print(). Under the stdio transport (the default and the
path used by all MCP clients per MCP_CONFIG.md: `uv run run_server.py`),
stdout is the JSON-RPC channel, so the plain-text lines emitted before
the initialize handshake corrupted the protocol stream. Strict MCP clients
(Claude Desktop / Cursor / ZCode / VS Code Copilot) treated this as a
fatal protocol error and reported the server as failed-to-start.
Redirect all diagnostic print() to sys.stderr (per MCP spec, only
JSON-RPC may use stdout). weknora_mcp_server.py already routes through
logging (stderr) and is unchanged.
Verified against a live backend (initialize -> tools/list (28 tools) ->
tools/call list_knowledge_bases); stdout first byte is now '{' with all
diagnostics on stderr.
* chore(mcp-server): publish package name as weknora-mcp
Rename the PyPI distribution name from weknora-mcp-server to weknora-mcp
(tools used: pyproject [project].name + setup.py name). The installed
console-script commands (weknora-mcp-server, weknora-server) and the
Python module (weknora_mcp_server) are unchanged for backward compatibility.
* fix(mcp-server): include upload_paths in wheel + bump to 1.0.1
The 1.0.0 wheel was missing upload_paths.py: it was absent from the
[tool.setuptools] py-modules list (and setup.py py_modules), so setuptools
never packed it. weknora_mcp_server.py line 26 does
`from upload_paths import resolve_upload_file_path, set_active_transport`,
so any path that fully imports the module — i.e. the MCP client initialize
handshake — crashed with ModuleNotFoundError. `--version` survived only
because argparse exits before that import runs.
Fix: add 'upload_paths' to py-modules (pyproject.toml + setup.py) and bump
to 1.0.1 (1.0.0 is immutable on PyPI). Also sync the user-facing version
strings (__version__, server_version, main --version) to 1.0.1.
* ci(mcp-server): add workflow.yml to build & publish to PyPI via OIDC
Adds .github/workflows/workflow.yml adapted from annopick/tuomin's ci.yml:
- test: matrix Python 3.10–3.13 (matches requires-python >=3.10), runs the
flat test_*.py suite in mcp-server/
- build: on mcp-server-v* tags, builds sdist + wheel via uv build, and
guards against the 1.0.0 regression by asserting upload_paths.py is in
the wheel before publishing
- publish: PyPI Trusted Publishing (OIDC, id-token: write) to weknora-mcp,
no API token needed
Publishing is gated on tags named mcp-server-v* to decouple from the Go
release workflow that already targets v* tags.
* fix(mcp-server): route diagnostics to stderr and fix packaging/CI
Prevent MCP stdio startup crashes by sending entry-script diagnostics to
stderr, package upload_paths in the wheel, and add unittest-based CI with
stdout purity regression tests.
---------
Co-authored-by: wizardchen <wizardchen@tencent.com>
The SSE transport's POST handler was mounted at /messages/, but the
SseServerTransport SDK prepends the Starlette root_path ("/sse") to
the endpoint parameter, instructing clients to POST to /sse/messages/.
This path mismatch caused MCP initialization requests to never reach
the handler, resulting in a 60s+ timeout on connect.
Fix: move the Mount to /sse/messages/ and place it before the /sse
catch-all route, since Starlette's Mount uses prefix matching and
/sse would otherwise intercept /sse/messages/ requests.
Align product copy, API docs, Swagger descriptions, and i18n strings
with workspace terminology while keeping internal tenant identifiers
and headers unchanged for API compatibility.
Record the active transport at run_stdio/run_sse/run_http startup so
create_knowledge_from_file path checks apply even when MCP_TRANSPORT
is not set in the environment.
Reject refresh JWTs in ValidateToken, revoke all user sessions on logout,
and restrict create_knowledge_from_file to allowed directories on network MCP transports.
GET with a JSON body was non-standard and confused integrators. Register
POST as the preferred method and keep GET for existing clients; update SDK,
MCP server, and API docs accordingly.
Refs: https://github.com/Tencent/WeKnora/issues/1727
- SSL verification now defaults to enabled; set WEKNORA_VERIFY_SSL=false to
opt out (with a logged warning). Fixes MITM risk from default-off TLS.
- WEKNORA_CHAT_TIMEOUT parse is now guarded with try/except ValueError so a
bad env value falls back to 300s instead of crashing at import.
- SSE streaming response is now closed via context manager (with response:)
to guarantee connection pool return even on early break.
- Replace asyncio.get_event_loop() (deprecated) with asyncio.get_running_loop()
in both chat and agent_chat handlers.
- create_session now calls resolve_kb_id() so KB names are accepted in addition
to UUIDs (consistent with chat / hybrid_search).
- knowledge_base_ids description changed from REQUIRED to Strongly recommended
to match actual schema optionality.
- run_sse() handle_sse rewritten as raw ASGI callable (scope, receive, send) to
avoid accessing Starlette private _send attribute.
- Fix main.py comment: http transport is Streamable HTTP (MCP spec), not long-polling.
Restore parameters that were inadvertently removed during refactoring.
- kb_id: Required knowledge base ID (architectural shift from KB-agnostic back to KB-bound sessions)
- max_rounds, enable_rewrite, fallback_response: Session strategy configuration
- summary_model_id: Model for response summarization
- title, description: Optional session metadata
These parameters enable AI agents to fully configure session behavior.
Add 3 read-only wiki tools (wiki_search, wiki_read_page,
wiki_index_view) to the Python MCP server, enabling external agents
like Claude Code and Codex to query WeKnora's LLM-generated wiki
pages following the LLM Wiki pattern.
Closes#1501
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Add docstrings and inline comments for key functions and complex logic
- Unify comment style, eliminate magic numbers and ambiguous variable names
- No functional changes, only improve maintainability