@c4a/mcp 0.4.15-beta.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 +116 -0
- package/index.js +22116 -0
- package/package.json +13 -0
package/README.md
ADDED
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# @c4a/mcp
|
|
2
|
+
|
|
3
|
+
MCP (Model Context Protocol) Server for [C4A](../../README.md) knowledge queries. Connects AI coding assistants — Claude Code, Cursor, Windsurf, and any MCP-compatible client — to your indexed codebases and business documents.
|
|
4
|
+
|
|
5
|
+
## What It Does
|
|
6
|
+
|
|
7
|
+
`@c4a/mcp` is a thin stdio client that bridges MCP-compatible LLM clients with C4A's REST API. It exposes a single **`c4a-query`** tool that accepts natural language queries and returns formatted text results.
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
┌──────────────────────────────────────┐
|
|
11
|
+
│ Claude Code / Cursor / Windsurf │
|
|
12
|
+
│ (LLM Client) │
|
|
13
|
+
│ ↕ MCP Protocol (stdio) │
|
|
14
|
+
├──────────────────────────────────────┤
|
|
15
|
+
│ @c4a/mcp │
|
|
16
|
+
│ (this package, thin client) │
|
|
17
|
+
│ - c4a-query tool │
|
|
18
|
+
│ ↕ HTTPS (REST API) │
|
|
19
|
+
├──────────────────────────────────────┤
|
|
20
|
+
│ C4A API Server │
|
|
21
|
+
│ POST /api/v1/query/ask │
|
|
22
|
+
└──────────────────────────────────────┘
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Install
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
# Run directly (recommended)
|
|
29
|
+
npx @c4a/mcp --api-url http://localhost:5100 --api-key c4a_xxx
|
|
30
|
+
|
|
31
|
+
# Or install globally
|
|
32
|
+
npm install -g @c4a/mcp
|
|
33
|
+
c4a-mcp --api-url http://localhost:5100 --api-key c4a_xxx
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Configuration
|
|
37
|
+
|
|
38
|
+
### Required Parameters
|
|
39
|
+
|
|
40
|
+
| Parameter | CLI Flag | Environment Variable | Description |
|
|
41
|
+
|-----------|----------|---------------------|-------------|
|
|
42
|
+
| **API URL** | `--api-url <url>` | `API_URL` | Base URL of your C4A API server (e.g. `http://localhost:5100`) |
|
|
43
|
+
| **API Key** | `--api-key <key>` | `API_KEY` | API key for authentication. Obtain from C4A server admin or via `POST /api/v1/auth/test-account/login` for local dev |
|
|
44
|
+
|
|
45
|
+
**Priority**: CLI flags take precedence over environment variables.
|
|
46
|
+
|
|
47
|
+
Both parameters are **required** — the server will exit with an error if either is missing.
|
|
48
|
+
|
|
49
|
+
### Claude Code
|
|
50
|
+
|
|
51
|
+
Add to your Claude Code MCP configuration (`~/.claude.json` or project `.claude/settings.json`):
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"mcpServers": {
|
|
56
|
+
"c4a": {
|
|
57
|
+
"command": "npx",
|
|
58
|
+
"args": ["@c4a/mcp"],
|
|
59
|
+
"env": {
|
|
60
|
+
"API_URL": "http://localhost:5100",
|
|
61
|
+
"API_KEY": "c4a_xxx"
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Cursor
|
|
69
|
+
|
|
70
|
+
Add to your Cursor MCP settings (`.cursor/mcp.json`):
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"mcpServers": {
|
|
75
|
+
"c4a": {
|
|
76
|
+
"command": "npx",
|
|
77
|
+
"args": ["@c4a/mcp"],
|
|
78
|
+
"env": {
|
|
79
|
+
"API_URL": "http://localhost:5100",
|
|
80
|
+
"API_KEY": "c4a_xxx"
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Windsurf / Other MCP Clients
|
|
88
|
+
|
|
89
|
+
The pattern is the same for any MCP-compatible client — set the command to `npx @c4a/mcp` and pass the two required environment variables.
|
|
90
|
+
|
|
91
|
+
## Supported Queries
|
|
92
|
+
|
|
93
|
+
The `c4a-query` tool automatically classifies your natural language query and routes it to the appropriate API:
|
|
94
|
+
|
|
95
|
+
| Query Type | Example |
|
|
96
|
+
|-----------|---------|
|
|
97
|
+
| Symbol lookup | "Where is validatePayment defined?" |
|
|
98
|
+
| Reverse tracing | "Who calls validatePayment?" |
|
|
99
|
+
| Forward tracing | "What does processOrder call?" |
|
|
100
|
+
| Semantic search | "Code related to payment timeout" |
|
|
101
|
+
| Structure browse | "Package structure of @c4a/api" |
|
|
102
|
+
|
|
103
|
+
See the tool description in your MCP client for the full list of supported query patterns and guidelines.
|
|
104
|
+
|
|
105
|
+
## Authentication
|
|
106
|
+
|
|
107
|
+
The MCP server authenticates with the C4A API using the provided API key via `Authorization: Bearer <api_key>` header. The key can be either:
|
|
108
|
+
|
|
109
|
+
- A **JWT token** — obtained from the login flow
|
|
110
|
+
- An **API Key** (`c4a_*` prefix) — created via the C4A admin interface
|
|
111
|
+
|
|
112
|
+
For local development with `allow_test_account` enabled, you can obtain a token via:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
curl -s -X POST http://localhost:5100/api/v1/auth/test-account/login | jq -r .token
|
|
116
|
+
```
|