Skip to content

Commit b5adafa

Browse files
butschsterbutschster
committed
add dynamic project switching section and update command examples
1 parent 347fd7b commit b5adafa

File tree

4 files changed

+199
-13
lines changed

4 files changed

+199
-13
lines changed

‎docs/.vitepress/config.mts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ export default withMermaid({
4646
text: 'MCP Server',
4747
items: [
4848
{text: 'Integration', link: '/mcp'},
49+
{text: 'Projects', link: '/mcp/projects'},
4950
{text: 'Filesystem', link: '/mcp/filesystem'},
5051
{text: 'Prompts', link: '/mcp/prompts'},
5152
{text: 'Tools', link: '/mcp/tools'},

‎docs/mcp/index.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -165,9 +165,8 @@ First of all you need to [install](https://claude.ai/download) Claude app and la
165165
{
166166
"mcpServers": {
167167
"ctx": {
168-
"command": "wsl.exe",
168+
"command": "bash.exe",
169169
"args": [
170-
"bash",
171170
"-c",
172171
"ctx server -c /path/to/project"
173172
]
@@ -213,9 +212,8 @@ the bash command:
213212
{
214213
"mcpServers": {
215214
"ctx": {
216-
"command": "wsl.exe",
215+
"command": "bash.exe",
217216
"args": [
218-
"bash",
219217
"-c",
220218
"export GITHUB_PAT=ghp_your_personal_access_token && export MCP_FILE_OPERATIONS=true && ctx server -c /path/to/project"
221219
]
@@ -225,3 +223,8 @@ the bash command:
225223
```
226224

227225
**Important:** After saving the configuration, restart the app.
226+
227+
## Dynamic Projects Switching
228+
229+
The MCP server supports dynamic project switching, allowing you to work with multiple projects. Read more about
230+
dynamic project switching in the [Projects](projects.md) section.

‎docs/mcp/projects.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Dynamic Project Switching
2+
3+
CTX allows you to manage multiple projects and seamlessly switch between them.
4+
5+
> **Note**: After switching projects, you may need to restart MCP clients (like Claude) to ensure they
6+
> recognize the new context.
7+
8+
**This feature is especially valuable for developers who:**
9+
10+
- Work on multiple projects simultaneously
11+
- Need to provide context from different codebases to AI assistants
12+
- Want to maintain separate configurations for different projects
13+
14+
## Using Dynamic Project Switching
15+
16+
With Project Switching, you can start the MCP server without specifying a project path:
17+
18+
```bash
19+
ctx server
20+
```
21+
22+
When the `-c` option is omitted, CTX will use the globally registered projects configuration. This means:
23+
24+
1. The server starts with the currently active project (if one is set)
25+
2. You can switch between registered projects using console commands
26+
3. AI assistants like Claude will always have access to the current project context
27+
28+
## Project Management Commands
29+
30+
CTX provides several commands for managing your projects:
31+
32+
## Adding a Project (`project:add`)
33+
34+
Register a new project with the system:
35+
36+
```bash
37+
ctx project:add <path> [--name=<alias>] [--config-file=<path>] [--env-file=<path>]
38+
```
39+
40+
**Example:**
41+
42+
The easiest way to add a project is to run the command from the project directory:
43+
44+
```bash
45+
ctx project:add . --name=my-backend
46+
```
47+
48+
If you want to specify environment variables for the project, you can do so with the `--env-file` option:
49+
50+
```bash
51+
ctx project:add . --name=my-backend --env-file=.env.dev
52+
```
53+
54+
**Arguments:**
55+
56+
- `path`: Path to the project directory. Use `.` for current directory.
57+
58+
**Options:**
59+
60+
- `--name`: Alias name for the project (optional)
61+
- `--config-file` or `-c`: Path to custom configuration file within the project (optional)
62+
- `--env-file` or `-e`: Path to .env file within the project (optional)
63+
64+
## Switching Between Projects (`project`)
65+
66+
Switch to a different registered project:
67+
68+
```bash
69+
ctx project [<path_or_alias>]
70+
```
71+
72+
**Arguments:**
73+
74+
- `path_or_alias`: Path or alias to the project (optional). If omitted, displays an interactive selection menu.
75+
76+
**Example:**
77+
78+
Switch to a project using its alias:
79+
80+
```bash
81+
ctx project my-backend
82+
```
83+
84+
or switch to a project using its path:
85+
86+
```bash
87+
ctx project .
88+
```
89+
90+
or you can omit the argument to see a list of all registered projects:
91+
92+
```bash
93+
ctx project
94+
```
95+
96+
### Listing Projects (`project:list` or `projects`)
97+
98+
View all registered projects:
99+
100+
```bash
101+
ctx project:list
102+
```
103+
104+
**Example output:**
105+
106+
```
107+
┌─────────────────────────────┬────────────────────┬──────────┬─────────────────┬─────────────────┬─────────┐
108+
│ Path │ Config File │ Env File │ Aliases │ Added │ Current │
109+
├─────────────────────────────┼────────────────────┼──────────┼─────────────────┼─────────────────┼─────────┤
110+
│ /home/user/projects/my-app │ │ │ my-app │ 2025-05-01 10:15│ │
111+
├─────────────────────────────┼────────────────────┼──────────┼─────────────────┼─────────────────┼─────────┤
112+
│ /home/user/projects/backend │ custom-context.yaml│ .env.dev │ my-backend, │ 2025-05-01 14:30│ active │
113+
│ │ │ │ backend │ │ │
114+
├─────────────────────────────┼────────────────────┼──────────┼─────────────────┼─────────────────┼─────────┤
115+
│ /home/user/projects/frontend│ │ │ my-ui │ 2025-05-02 09:45│ │
116+
└─────────────────────────────┴────────────────────┴──────────┴─────────────────┴─────────────────┴─────────┘
117+
```
118+
119+
## Configuring MCP Server for Project Switching
120+
121+
In your Claude app configuration, set up the MCP Server without specifying a project path:
122+
123+
### Linux Configuration
124+
125+
```json
126+
{
127+
"mcpServers": {
128+
"ctx": {
129+
"command": "ctx",
130+
"args": [
131+
"server"
132+
]
133+
}
134+
}
135+
}
136+
```
137+
138+
### Windows Configuration
139+
140+
```json
141+
{
142+
"mcpServers": {
143+
"ctx": {
144+
"command": "C:\\ctx.exe",
145+
"args": [
146+
"server"
147+
]
148+
}
149+
}
150+
}
151+
```
152+
153+
### Windows with WSL Configuration
154+
155+
```json
156+
{
157+
"mcpServers": {
158+
"ctx": {
159+
"command": "bash.exe",
160+
"args": [
161+
"-c",
162+
"ctx server"
163+
]
164+
}
165+
}
166+
}
167+
```
168+
169+
This configuration allows the MCP server to automatically use the currently active project from your project registry
170+
without requiring a specific path at startup time.

‎docs/mcp/tools.md‎

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,16 @@ The tools system can be configured using environment variables to enable or disa
1010

1111
### General Configuration
1212

13-
| Variable | Description | Default |
14-
|------------------------------|--------------------------------------------|---------|
15-
| `MCP_CUSTOM_TOOLS_ENABLE` | Enable/disable custom tools | `true` |
16-
| `MCP_TOOL_MAX_RUNTIME` | Maximum runtime for a command in seconds | `30` |
17-
| `MCP_TOOL_COMMAND_EXECUTION` | Enable/disable command execution | `true` |
18-
| `MCP_FILE_OPERATIONS` | Master switch for all file operation tools | `true` |
19-
| `MCP_FILE_WRITE` | Enable/disable file write operations | `true` |
20-
| `MCP_FILE_APPLY_PATCH` | Enable/disable applying patches to files | `false` |
21-
| `MCP_FILE_DIRECTORIES_LIST` | Enable/disable directory listing | `true` |
13+
| Variable | Description | Default |
14+
|------------------------------|---------------------------------------------|---------|
15+
| `MCP_CUSTOM_TOOLS_ENABLE` | Enable/disable custom tools | `true` |
16+
| `MCP_TOOL_MAX_RUNTIME` | Maximum runtime for a command in seconds | `30` |
17+
| `MCP_TOOL_COMMAND_EXECUTION` | Enable/disable command execution | `true` |
18+
| `MCP_FILE_OPERATIONS` | Master switch for all file operation tools | `true` |
19+
| `MCP_FILE_WRITE` | Enable/disable file write operations | `true` |
20+
| `MCP_FILE_APPLY_PATCH` | Enable/disable applying patches to files | `false` |
21+
| `MCP_FILE_DIRECTORIES_LIST` | Enable/disable directory listing | `true` |
22+
| `MCP_DOCS_TOOLS_ENABLED` | Enable/disable Context7 documentation tools | `true` |
2223

2324
## Available Tool Categories
2425

@@ -56,6 +57,17 @@ Experimental tools for working with prompts.
5657
| `prompt-get` | Retrieve a specific prompt | `MCP_PROMPT_OPERATIONS` | `false` (experimental) |
5758
| `prompts-list` | List all available prompts | `MCP_PROMPT_OPERATIONS` | `false` (experimental) |
5859

60+
### Docs Tools (`MCP_DOCS_TOOLS_ENABLED`)
61+
62+
Search for documentation libraries available on the Context7 service.
63+
64+
#### Parameters
65+
66+
| Parameter | Type | Required | Default | Description |
67+
|-----------|---------|----------|---------|----------------------------------------------|
68+
| `query` | string | Yes | - | Search query to find documentation libraries |
69+
| `limit` | integer | No | 5 | Maximum number of results to return |
70+
5971
### Always Available Tools
6072

6173
These tools are always available regardless of environment configuration:

0 commit comments

Comments
 (0)