@lucern/mcp 0.2.0-alpha.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +109 -0
- package/agent.md +33 -0
- package/bin/lucern-mcp.js +11 -0
- package/dist/.generated +2 -0
- package/dist/index.js +11162 -0
- package/dist/index.js.map +1 -0
- package/package.json +56 -0
package/README.md
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# @lucern/mcp
|
|
2
|
+
|
|
3
|
+
Standalone MCP server for Lucern's reasoning runtime.
|
|
4
|
+
|
|
5
|
+
## Package status
|
|
6
|
+
|
|
7
|
+
- Distribution target: private/internal registry
|
|
8
|
+
- License: UNLICENSED
|
|
9
|
+
- Expected auth: `LUCERN_API_KEY` machine credential
|
|
10
|
+
- Canonical hosted/remote auth: service principal bearer token (`lk_...` / `lsk_...`)
|
|
11
|
+
- Compatibility auth: tenant API key (`luc_...` / `stk_...`)
|
|
12
|
+
|
|
13
|
+
## Run
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npx @lucern/mcp --api-key lk_... --base-url https://your-lucern-host
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Env vars:
|
|
20
|
+
|
|
21
|
+
- `LUCERN_API_KEY` (required)
|
|
22
|
+
- `LUCERN_BASE_URL` (optional)
|
|
23
|
+
- `LUCERN_PROJECT_ID` (optional)
|
|
24
|
+
- `LUCERN_MCP_TRANSPORT` (`stdio` or `http`, default: `stdio`)
|
|
25
|
+
- `LUCERN_MCP_HOST` (HTTP only, default: `127.0.0.1`)
|
|
26
|
+
- `LUCERN_MCP_PORT` (HTTP only, default: `8080`)
|
|
27
|
+
- `LUCERN_MCP_PATH` (HTTP only, default: `/mcp`)
|
|
28
|
+
- `LUCERN_MCP_HEALTH_PATH` (HTTP only, default: `/health`)
|
|
29
|
+
- `LUCERN_MCP_SERVER_AUTH_TOKEN` (HTTP only, optional)
|
|
30
|
+
- `LUCERN_MCP_ALLOW_API_KEY_PASSTHROUGH` (HTTP only, default: `true`)
|
|
31
|
+
|
|
32
|
+
## Remote MCP (HTTP) mode
|
|
33
|
+
|
|
34
|
+
Hosted/server mode with Streamable HTTP transport:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
npx @lucern/mcp \
|
|
38
|
+
--transport http \
|
|
39
|
+
--host 0.0.0.0 \
|
|
40
|
+
--port 8080 \
|
|
41
|
+
--path /mcp \
|
|
42
|
+
--health-path /health \
|
|
43
|
+
--base-url https://your-lucern-host \
|
|
44
|
+
--server-auth-token your-shared-token \
|
|
45
|
+
--allow-api-key-passthrough
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Auth behavior:
|
|
49
|
+
|
|
50
|
+
- If `--api-key` is provided, the server uses that credential for all upstream Lucern API calls.
|
|
51
|
+
- Otherwise (default), the server accepts inbound `Authorization: Bearer lk_/lsk_...` service principal tokens plus `x-lucern-key` or `Authorization: Bearer luc_/stk_...` tenant API keys and forwards them upstream.
|
|
52
|
+
- If `--server-auth-token` is provided, incoming requests must include `Authorization: Bearer <token>` or `x-lucern-mcp-token: <token>`.
|
|
53
|
+
|
|
54
|
+
Canonical hosted endpoint:
|
|
55
|
+
|
|
56
|
+
```text
|
|
57
|
+
https://your-lucern-host/api/platform/mcp
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Example remote connector config:
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
{
|
|
64
|
+
"mcpServers": {
|
|
65
|
+
"lucern": {
|
|
66
|
+
"url": "https://your-lucern-host/api/platform/mcp",
|
|
67
|
+
"headers": {
|
|
68
|
+
"Authorization": "Bearer lk_..."
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Surface distinction
|
|
76
|
+
|
|
77
|
+
This package is the **external package MCP** surface (`packages/mcp`) intended for Claude Code/CoWork and SDK consumers.
|
|
78
|
+
|
|
79
|
+
It is intentionally separate from the **internal Convex MCP** runtime under `convex/mcp/*` used by StackOS internals.
|
|
80
|
+
|
|
81
|
+
See `docs/lucern-replatform/api/mcp-surface-separation.md` for boundary details.
|
|
82
|
+
|
|
83
|
+
## Claude Code config
|
|
84
|
+
|
|
85
|
+
```json
|
|
86
|
+
{
|
|
87
|
+
"mcpServers": {
|
|
88
|
+
"lucern": {
|
|
89
|
+
"command": "npx",
|
|
90
|
+
"args": ["@lucern/mcp"],
|
|
91
|
+
"env": {
|
|
92
|
+
"LUCERN_API_KEY": "lk_...",
|
|
93
|
+
"LUCERN_BASE_URL": "https://your-lucern-host",
|
|
94
|
+
"LUCERN_PROJECT_ID": "project_123"
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## Exports
|
|
102
|
+
|
|
103
|
+
- `createLucernStandaloneMcpServer`
|
|
104
|
+
- `startLucernMcpStdioServer`
|
|
105
|
+
- `createLucernMcpHttpRequestHandler`
|
|
106
|
+
- `startLucernMcpHttpServer`
|
|
107
|
+
- `runLucernMcpCli`
|
|
108
|
+
- `LUCERN_AGENT_MD`
|
|
109
|
+
- `buildLucernObserverPrompt`
|
package/agent.md
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Lucern MCP Agent Instructions
|
|
2
|
+
|
|
3
|
+
You are connected to Lucern, a reasoning graph runtime.
|
|
4
|
+
|
|
5
|
+
## Observe
|
|
6
|
+
|
|
7
|
+
Continuously detect:
|
|
8
|
+
|
|
9
|
+
1. New claims that should become beliefs
|
|
10
|
+
2. New supporting/challenging material that should become evidence
|
|
11
|
+
3. Unknowns that should become questions
|
|
12
|
+
4. Conflicts that should become contradictions
|
|
13
|
+
|
|
14
|
+
## Confirm Before Mutation
|
|
15
|
+
|
|
16
|
+
Always ask for confirmation before writing:
|
|
17
|
+
|
|
18
|
+
`🔍 Lucern detected: [event summary] -> Want me to log this?`
|
|
19
|
+
|
|
20
|
+
## Context-First Execution
|
|
21
|
+
|
|
22
|
+
Before deep reasoning answers:
|
|
23
|
+
|
|
24
|
+
1. Load relevant graph context (beliefs, evidence, questions, contradictions)
|
|
25
|
+
2. Summarize confidence and unresolved tensions
|
|
26
|
+
3. Then propose updates or next actions
|
|
27
|
+
|
|
28
|
+
## Safety
|
|
29
|
+
|
|
30
|
+
1. Do not fabricate evidence.
|
|
31
|
+
2. Do not auto-resolve contradictions.
|
|
32
|
+
3. Keep rationale and provenance in every write flow.
|
|
33
|
+
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { runLucernMcpCli } from "../dist/lib/platform/mcp/cli.js";
|
|
3
|
+
|
|
4
|
+
runLucernMcpCli().catch((error) => {
|
|
5
|
+
console.error(
|
|
6
|
+
error instanceof Error
|
|
7
|
+
? error.message
|
|
8
|
+
: `lucern-mcp failed: ${String(error)}`
|
|
9
|
+
);
|
|
10
|
+
process.exit(1);
|
|
11
|
+
});
|
package/dist/.generated
ADDED