You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .amf/knowledge/note/project.md
+7-4Lines changed: 7 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -7,8 +7,11 @@
7
7
***Target Framework:**`metacontract` (mc) - A Foundry-based framework implementing ERC-7546 (Upgradeable Clone for Scalable Contracts) focusing on upgradeability, modularity, scalability, and testability. Optimized for AI integration and DevOps efficiency.
8
8
***Protocol:** Model Context Protocol (MCP) - An open protocol standardizing interactions between AI applications (clients/hosts like IDEs) and external tools/data sources (servers like `mc-mcp`).
9
9
***Core Functionality (MCP Tools):** Implemented using `rmcp` SDK's `#[tool]` and `#[tool(tool_box)]` annotations.
10
-
***`forge_test`:** Run `forge test` in the workspace.
11
-
***`search_docs`:** Semantic search over `mc` documentation and user-configured sources, returning structured JSON (`Vec<SearchResult>`).
10
+
***Naming convention:** All MCP tools should be named with the `mc_` prefix followed by the function name (e.g., `mc_setup`, `mc_deploy`, `mc_upgrade`, `mc_lint`, `mc_test`, `mc_search_docs`).
11
+
***Deploy/Upgrade tool dry-run support:**`mc_deploy` and `mc_upgrade` must support dry-run mode (default), toggled by the `broadcast: true` argument. The script path is configured via `mcp_config.toml ([scripts].deploy / [scripts].upgrade)`. Without `broadcast: true`, the tool should simulate the operation (dry-run); with `broadcast: true`, it should execute the actual deployment/upgrade (requires `rpc_url` and `private_key_env_var` to be set in `mcp_config.toml` under `[scripts]`).
12
+
***`mc_test`:** Run `forge test` in the workspace.
13
+
***`mc_search_docs`:** Semantic search over `mc` documentation and user-configured sources, returning structured JSON (`Vec<SearchResult>`).
14
+
***`mc_setup`**: Initialize a new Foundry project using the `metacontract/template`. Requires an empty directory.
12
15
13
16
## 2. Technology Stack
14
17
@@ -19,7 +22,7 @@
19
22
***Text Embedding:** Local Sentence Transformer (e.g., all-MiniLM-L6-v2) via `fastembed-rs`
Copy file name to clipboardExpand all lines: README.md
+61-6Lines changed: 61 additions & 6 deletions
Original file line number
Diff line number
Diff line change
@@ -9,8 +9,12 @@ A Model Context Protocol (MCP) server for the [metacontract (mc)](https://github
9
9
**mc-mcp** is an extensible MCP server designed for the [metacontract](https://github.com/metacontract/mc) (mc) framework.
10
10
It enables AI-powered smart contract development workflows by exposing tools such as:
11
11
12
-
-**`forge_test`**: Run Foundry tests (`forge test`) in your workspace.
13
-
-**`search_docs`**: Perform semantic search over mc documentation and user-configured sources, returning structured JSON results.
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.
14
18
15
19
---
16
20
@@ -105,15 +109,18 @@ See [RooCode's documentation](https://github.com/RooVetGit/Roo-Code) for details
105
109
### 5. Develop your smart contract
106
110
107
111
- Use your MCP-compatible Agent/IDE to interact with mc-mcp
108
-
- Design, search docs, and run TDD cycles (`forge_test`, `search_docs`, etc.)
112
+
- Design, search docs, and run TDD cycles (`mc_test`, `mc_search_docs`, etc.)
109
113
110
114
### Configuration Example
111
115
112
116
Create a file named `mcp_config.toml` in your project root:
private_key_env_var = "PRIVATE_KEY"# Name of the env var holding the deployer's private key
132
148
```
133
149
134
-
-`prebuilt_index_path` ... (optional) Path to a prebuilt index (jsonl or gzipped jsonl). If set, it will be loaded and upserted into Qdrant on startup.
150
+
-`prebuilt_index_path` ... (optional) Path to a prebuilt index (jsonl or gzipped jsonl). If set, it overrides the default cache location. The index will be loaded and upserted into Qdrant on startup.
135
151
- Each `[[reference.sources]]` must have `name`, `source_type` (usually `local`), and `path` (relative to the execution directory).
152
+
-`[scripts].deploy` and `[scripts].upgrade` specify the default Foundry script paths used by the `mc_deploy` and `mc_upgrade` tools respectively.
153
+
-`[scripts].rpc_url` and `[scripts].private_key_env_var` are required when using `mc_deploy` or `mc_upgrade` with the `broadcast: true` argument. `forge` will use these to send the transaction.
136
154
- All paths must exist and be directories, or indexing will fail.
137
155
138
156
See also: [config.rs](src/config.rs) for the full config structure.
@@ -151,9 +169,46 @@ See also: [config.rs](src/config.rs) for the full config structure.
151
169
## Development
152
170
153
171
-**TDD**: Test-Driven Development is enforced (unit/integration tests)
154
-
-**Integration tests**: Use [testcontainers](https://github.com/testcontainers/testcontainers-rs) for Qdrant
172
+
-**Integration tests**: Use [testcontainers](https://github.com/testcontainers/testcontainers-rs) for Qdrant, ensuring isolated and stable test environments.
155
173
-**CI/CD**: GitHub Actions for build, test, and prebuilt index artifact management
156
174
175
+
## Testing & Troubleshooting
176
+
177
+
Some tests (especially integration tests and embedding-related tests) may fail due to OS file descriptor limits or cache lock issues.
178
+
179
+
### Common Commands (via Makefile)
180
+
181
+
-**Unit tests (lib only, with cache lock cleanup, single-threaded):**
182
+
```sh
183
+
make test-lib
184
+
```
185
+
-**All tests (recommended: increase ulimit before running):**
186
+
```sh
187
+
ulimit -n 4096
188
+
make test-all
189
+
```
190
+
-**Integration tests (single-threaded):**
191
+
```sh
192
+
make test-integration
193
+
```
194
+
-**Clean embedding model cache:**
195
+
```sh
196
+
make clean-cache
197
+
```
198
+
199
+
### Troubleshooting
200
+
201
+
-**If you see `Too many open files` errors:**
202
+
- Increase the file descriptor limit in your shell *before* running tests: `ulimit -n 4096`
203
+
- Run tests sequentially: `cargo test -- --test-threads=1` (or use `make test-lib` / `make test-integration`)
204
+
-**If you see `.lock` errors (related to embedding model cache):**
- Ensure the mock script setup within the specific test file (`src/main.rs` tests) is correct.
208
+
-**Note:**
209
+
- The Makefile provides handy shortcuts for common tasks, but some OS or CI environments may require manual adjustment of file descriptor limits (`ulimit`).
0 commit comments