Skip to content

Commit a6856e4

Browse files
kaihiroikaihiroi
committed
docs: update README.md to enhance tool descriptions, clarify project setup instructions, and improve overall structure for better readability
1 parent 8e83865 commit a6856e4

File tree

1 file changed

+82
-68
lines changed

1 file changed

+82
-68
lines changed

‎README.md

Lines changed: 82 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -9,55 +9,26 @@ A Model Context Protocol (MCP) server for the [metacontract (mc)](https://github
99
**mc-mcp** is an extensible MCP server designed for the [metacontract](https://github.com/metacontract/mc) (mc) framework.
1010
It enables AI-powered smart contract development workflows by exposing tools such as:
1111

12-
- **`mc_search_docs`**: Perform semantic search over mc documentation and user-configured sources, returning structured JSON results.
13-
- **`mc_test`**: Run Foundry tests (`forge test`) in your workspace.
14-
- **`mc_setup`**: Initialize a new Foundry project using the `metacontract/template` (requires an empty directory).
15-
- **`mc_deploy`**: Deploy contracts using the script specified in `mcp_config.toml`. Supports dry-run (default) and broadcast mode (`broadcast: true` argument).
16-
- **`mc_upgrade`**: Upgrade contracts using the script specified in `mcp_config.toml`. Supports dry-run and broadcast mode.
17-
- **`mc_lint`**: (Coming Soon) Lint project files for best practices and errors.
18-
19-
---
20-
21-
## Features
22-
23-
- **Layered (Onion) Architecture** for maintainability and testability
24-
- **Rust** implementation for performance and safety
25-
- **MCP SDK** (`modelcontextprotocol-rust-sdk`) with `#[tool]` annotation-based tool definition
26-
- **Qdrant** (embedded vector DB) for fast semantic search
27-
- **Local embedding generation** using [fastembed-rs](https://github.com/kuvaus/fastembed-rs)
28-
- **Markdown parsing** with [comrak](https://github.com/kivikakk/comrak)
29-
- **Flexible configuration** via [figment](https://github.com/SergioBenitez/figment)
30-
- **Structured logging** with [tracing](https://github.com/tokio-rs/tracing)
31-
- **CI/CD**: Prebuilt documentation index is generated, compressed, and published as a GitHub Release asset
32-
33-
---
34-
35-
## Architecture
36-
37-
- **Library + Binary crate** structure
38-
- **Domain / Application / Infrastructure** layering
39-
- **Manual Dependency Injection**
40-
- **Strict inward dependency rule** (Entry Point → Application → Domain ← Infrastructure)
41-
- **Prebuilt index**: Downloaded automatically from GitHub Releases on first run (not included in the crate)
12+
- **`mc_search_docs_semantic`**: Performs semantic search over mc documentation and user-configured sources, returning structured JSON results.
13+
- **`mc_setup`**: Initializes a new Foundry project using the `metacontract/template`. (Set `setup.force=true` in the config if the directory is not empty.)
14+
- **`mc_test`**: Runs Foundry tests (`forge test`) in your workspace.
15+
- **`mc_deploy`**: Deploys contracts using the script specified in `mcp_config.toml`. Supports dry-run (default) and broadcast mode (`broadcast: true` argument).
16+
- **`mc_upgrade`**: Upgrades contracts using the script specified in `mcp_config.toml`. Supports dry-run and broadcast mode.
17+
- **`mc_lint`**: _(Coming Soon)_ Lints project files for best practices and errors.
18+
- **`mc_erc7201_slot`**: Calculates the namespaced storage slot using ERC-7201.
4219

4320
---
4421

4522
## Configuration and Project Root
4623

4724
**Project Root is always specified by the `MC_PROJECT_ROOT` environment variable.**
4825

26+
- The `MC_PROJECT_ROOT` environment variable is required because path resolution is delegated to the MCP client implementation. This ensures consistent and reliable behavior across different environments.
4927
- Set `MC_PROJECT_ROOT` to your project root directory before running any mc-mcp command or tool.
5028
- All configuration, including `mcp_config.toml`, is expected to be in this directory.
5129
- If `MC_PROJECT_ROOT` is not set or does not exist, mc-mcp will return an error and not start.
5230
- If `mcp_config.toml` is missing, mc-mcp will use built-in defaults and log a warning.
5331

54-
### Example: Setting up and running mc-mcp
55-
56-
```sh
57-
export MC_PROJECT_ROOT=/path/to/your/project
58-
mc-mcp
59-
```
60-
6132
### Example: Project Structure
6233

6334
```
@@ -71,43 +42,30 @@ mc-mcp
7142
### Configuration File (`mcp_config.toml`)
7243
- Place this file directly under your `MC_PROJECT_ROOT` directory.
7344
- If omitted, mc-mcp will use default settings for all configuration values.
74-
- See below for a sample config and field descriptions.
45+
- See below for a [sample config and field descriptions](#configuration-example).
7546

7647
---
7748

7849
## Getting Started
7950

8051
### 1. Install mc-mcp (as a CLI tool)
8152

82-
# If published on crates.io (recommended for most users)
53+
```bash
54+
# recommended for most users
8355
cargo install mc-mcp
56+
```
8457

58+
```bash
8559
# Or, to use the latest development version from GitHub:
8660
cargo install --git https://github.com/metacontract/mc-mcp.git
8761

88-
# (Alternatively, you can clone and build manually:)
62+
# Alternatively, you can clone and build manually:
8963
git clone https://github.com/metacontract/mc-mcp.git
9064
cd mc-mcp
9165
cargo build --release
92-
93-
### 2. Initialize a new mc project
94-
95-
```sh
96-
forge init <your-project-name> -t metacontract/template
97-
cd <your-project-name>
9866
```
9967

100-
### 3. Start the mc-mcp server
101-
102-
```sh
103-
mc-mcp
104-
# or
105-
/path/to/mc-mcp/target/release/mc-mcp
106-
```
107-
108-
- On first startup, the prebuilt documentation index (`prebuilt_index.jsonl.gz`) will be downloaded from the latest GitHub Release if not present.
109-
110-
### 4. Connect with an MCP client
68+
### 2. Add to your MCP client
11169

11270
mc-mcp works with any MCP-compatible client, such as:
11371
- [Cursor](https://cursor.so/)
@@ -116,19 +74,21 @@ mc-mcp works with any MCP-compatible client, such as:
11674

11775
#### Example: Cursor
11876

119-
Add your MCP server in the settings (`mcp.json`):
77+
Add your MCP server in the settings (`./cursor/mcp.json` or global settings):
12078

12179
```json
12280
{
12381
"mcpServers": {
12482
"mc-mcp": {
12583
"command": "mc-mcp", // or "/path/to/mc-mcp/target/release/mc-mcp",
126-
"args": [],
127-
"cwd": "/path/to/your/project"
84+
"env": {
85+
"MC_PROJECT_ROOT": "/absolute-path/to/your/project"
86+
}
12887
}
12988
}
13089
}
13190
```
91+
13292
#### Example: Cline
13393

13494
Cline auto-detects MCP servers in your workspace.
@@ -139,10 +99,41 @@ For advanced configuration, see [Cline's documentation](https://github.com/cline
13999
RooCode supports MCP integration out of the box.
140100
See [RooCode's documentation](https://github.com/RooVetGit/Roo-Code) for details.
141101

142-
### 5. Develop your smart contract
102+
```json
103+
{
104+
"mcpServers": {
105+
"mc-mcp": {
106+
"disabled": false,
107+
"timeout": 60,
108+
"command": "mc-mcp",
109+
"transportType": "stdio",
110+
"alwaysAllow": ["mc_setup", "mc_search_docs_semantic", "mc_test", "mc_deploy", "mc_upgrade"], // if needed
111+
"env": {
112+
"MC_PROJECT_ROOT": "/absolute-path/to/your/project"
113+
}
114+
}
115+
}
116+
}
117+
```
118+
119+
Then, your MCP client starts the **mc-mcp** server automatically.
120+
- On first startup, the prebuilt documentation index (`prebuilt_index.jsonl.gz`) will be downloaded from the latest GitHub Release if not present.
121+
122+
### 3. Initialize a new mc project
123+
124+
You can simply instruct your agent to "setup mc project".
125+
126+
or, manual setup
127+
128+
```sh
129+
forge init <your-project-name> -t metacontract/template
130+
cd <your-project-name>
131+
```
132+
133+
### 4. Develop your smart contract
143134

144135
- Use your MCP-compatible Agent/IDE to interact with mc-mcp
145-
- Design, search docs, and run TDD cycles (`mc_test`, `mc_search_docs`, etc.)
136+
- Design, search docs, and run TDD cycles (`mc_test`, `mc_search_docs_semantic`, etc.)
146137

147138
### Configuration Example
148139

@@ -190,6 +181,30 @@ See also: [config.rs](src/config.rs) for the full config structure.
190181

191182
---
192183

184+
## Features
185+
186+
- **Layered (Onion) Architecture** for maintainability and testability
187+
- **Rust** implementation for performance and safety
188+
- **MCP SDK** (`modelcontextprotocol-rust-sdk`) with `#[tool]` annotation-based tool definition
189+
- **Qdrant** (embedded vector DB) for fast semantic search
190+
- **Local embedding generation** using [fastembed-rs](https://github.com/kuvaus/fastembed-rs)
191+
- **Markdown parsing** with [comrak](https://github.com/kivikakk/comrak)
192+
- **Flexible configuration** via [figment](https://github.com/SergioBenitez/figment)
193+
- **Structured logging** with [tracing](https://github.com/tokio-rs/tracing)
194+
- **CI/CD**: Prebuilt documentation index is generated, compressed, and published as a GitHub Release asset
195+
196+
---
197+
198+
## Architecture
199+
200+
- **Library + Binary crate** structure
201+
- **Domain / Application / Infrastructure** layering
202+
- **Manual Dependency Injection**
203+
- **Strict inward dependency rule** (Entry Point → Application → Domain ← Infrastructure)
204+
- **Prebuilt index**: Downloaded automatically from GitHub Releases on first run (not included in the crate)
205+
206+
---
207+
193208
## Project Structure
194209

195210
- `src/domain/` — Core business logic, traits, entities
@@ -211,14 +226,13 @@ Some tests (especially integration tests and embedding-related tests) may fail d
211226

212227
### Common Commands (via Makefile)
213228

214-
- **Unit tests (lib only, with cache lock cleanup, single-threaded):**
229+
- **All tests (include ignored tests):**
215230
```sh
216-
make test-lib
231+
make test-all
217232
```
218-
- **All tests (recommended: increase ulimit before running):**
233+
- **Unit tests (lib only, with cache lock cleanup, single-threaded):**
219234
```sh
220-
ulimit -n 4096
221-
make test-all
235+
make test-lib
222236
```
223237
- **Integration tests (single-threaded):**
224238
```sh
@@ -240,7 +254,7 @@ Some tests (especially integration tests and embedding-related tests) may fail d
240254
- Ensure the mock script setup within the specific test file (`src/main.rs` tests) is correct.
241255
- **Note:**
242256
- The Makefile provides handy shortcuts for common tasks, but some OS or CI environments may require manual adjustment of file descriptor limits (`ulimit`).
243-
- See each Makefile target for details.
257+
- See each Makefile target for more details.
244258

245259
---
246260

0 commit comments

Comments
 (0)