cf-mcp 0.9.2

data/lib/cf/mcp/templates/script.js

@@ -0,0 +1,292 @@
+import { h, render } from 'https://esm.sh/preact@10';
+import { useState, useEffect, useRef, useCallback } from 'https://esm.sh/preact@10/hooks';
+import htm from 'https://esm.sh/htm@3';
+
+const html = htm.bind(h);
+
+const TOOLS = TOOL_SCHEMAS_PLACEHOLDER;
+const CATEGORIES = CATEGORIES_PLACEHOLDER;
+const TOPICS = TOPICS_PLACEHOLDER;
+const CHANGELOG = CHANGELOG_PLACEHOLDER;
+
+// Helper to render topic options (used in multiple places)
+const renderTopicOptions = () =>
+  TOPICS.map(topic => html`<option value=${topic.name}>${topic.name.replace(/_/g, ' ')}</option>`);
+
+// Reusable select field component
+function SelectField({ id, label, value, onChange, required, placeholder, options }) {
+  return html`
+    <div class="form-group">
+      <label class="form-label" for=${id}>${label}</label>
+      <select id=${id} class="form-select" value=${value} onChange=${onChange} required=${required}>
+        <option value="">${placeholder}</option>
+        ${options}
+      </select>
+    </div>
+  `;
+}
+
+// Custom hook for MCP tool calls
+function useMcpToolCall() {
+  const [result, setResult] = useState({ loading: false, error: null, content: null });
+
+  const callTool = useCallback(async (toolName, args = {}, loadingText = 'Loading...') => {
+    setResult({ loading: true, loadingText, error: null, content: null });
+
+    try {
+      const response = await fetch('/http', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Accept': 'application/json, text/event-stream'
+        },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          id: Date.now(),
+          method: 'tools/call',
+          params: { name: toolName, arguments: args }
+        })
+      });
+
+      const data = await response.json();
+
+      if (data.error) {
+        setResult({ loading: false, error: 'Error: ' + (data.error.message || JSON.stringify(data.error)), content: null });
+      } else if (data.result?.content) {
+        const content = data.result.content[0];
+        const text = content.text || JSON.stringify(content);
+        setResult({
+          loading: false,
+          error: data.result.isError ? text : null,
+          content: data.result.isError ? null : text
+        });
+      } else {
+        setResult({ loading: false, error: null, content: JSON.stringify(data, null, 2) });
+      }
+    } catch (err) {
+      setResult({ loading: false, error: 'Network error: ' + err.message, content: null });
+    }
+  }, []);
+
+  const reset = useCallback(() => {
+    setResult({ loading: false, error: null, content: null });
+  }, []);
+
+  return { result, callTool, reset };
+}
+
+// Shared ResultArea component
+function ResultArea({ result }) {
+  const containerRef = useRef(null);
+
+  useEffect(() => {
+    if (result.content && containerRef.current) {
+      containerRef.current.innerHTML = marked.parse(result.content);
+      convertListsToDefinitionLists(containerRef.current);
+    }
+  }, [result.content]);
+
+  if (result.loading) {
+    return html`<div class="result-area visible"><span class="loading">${result.loadingText || 'Loading...'}</span></div>`;
+  }
+
+  if (result.error) {
+    return html`<div class="result-area visible error">${result.error}</div>`;
+  }
+
+  if (result.content) {
+    return html`<div class="result-area visible success" ref=${containerRef}></div>`;
+  }
+
+  return html`<div class="result-area"></div>`;
+}
+
+function convertListsToDefinitionLists(container) {
+  const lists = container.querySelectorAll('ul');
+  lists.forEach(ul => {
+    const items = ul.querySelectorAll('li');
+    const isDefinitionList = Array.from(items).every(li => li.innerHTML.includes(' — '));
+    if (!isDefinitionList || items.length === 0) return;
+
+    const dl = document.createElement('dl');
+    items.forEach(li => {
+      const parts = li.innerHTML.split(' — ');
+      if (parts.length >= 2) {
+        const dt = document.createElement('dt');
+        dt.innerHTML = parts[0];
+        const dd = document.createElement('dd');
+        dd.innerHTML = parts.slice(1).join(' — ');
+        dl.appendChild(dt);
+        dl.appendChild(dd);
+      }
+    });
+    ul.replaceWith(dl);
+  });
+}
+
+// Helper to create a select input
+function renderSelect(id, value, onChange, required, placeholder, options) {
+  return html`
+    <select id=${id} class="form-select" value=${value} onChange=${onChange} required=${required}>
+      <option value="">${placeholder}</option>
+      ${options}
+    </select>
+  `;
+}
+
+// Form field component
+function FormField({ name, propDef, required, value, onChange, toolName }) {
+  const id = `field-${name}`;
+  const description = propDef.description || '';
+  const handleChange = e => onChange(name, e.target.value);
+
+  let input;
+
+  if (propDef.enum) {
+    input = renderSelect(id, value, handleChange, required, '-- Select --',
+      propDef.enum.map(val => html`<option value=${val}>${val}</option>`));
+  } else if (propDef.type === 'integer') {
+    const attrs = name === 'limit' ? { min: 1, max: 20 } : {};
+    input = html`
+      <input
+        type="number"
+        id=${id}
+        class="form-input"
+        placeholder=${description}
+        value=${value}
+        onChange=${e => onChange(name, e.target.value ? parseInt(e.target.value, 10) : '')}
+        required=${required}
+        ...${attrs}
+      />
+    `;
+  } else if (name === 'category') {
+    input = renderSelect(id, value, handleChange, required, '-- All Categories --',
+      CATEGORIES.map(cat => html`<option value=${cat}>${cat}</option>`));
+  } else if (name === 'name' && toolName === 'cf_get_topic') {
+    input = renderSelect(id, value, handleChange, required, '-- Select Topic --', renderTopicOptions());
+  } else {
+    input = html`
+      <input
+        type="text"
+        id=${id}
+        class="form-input"
+        placeholder=${description}
+        value=${value}
+        onInput=${e => onChange(name, e.target.value)}
+        required=${required}
+      />
+    `;
+  }
+
+  return html`
+    <div class="form-group">
+      <label class="form-label" for=${id}>
+        ${name} ${required && html`<span class="required">*</span>`}
+      </label>
+      ${input}
+      ${description && html`<div class="form-hint">${description}</div>`}
+    </div>
+  `;
+}
+
+// Tool Explorer component
+function ToolExplorer() {
+  const [selectedTool, setSelectedTool] = useState(TOOLS[0]?.name || '');
+  const [formValues, setFormValues] = useState({ limit: 20 });
+  const { result, callTool, reset } = useMcpToolCall();
+
+  const tool = TOOLS.find(t => t.name === selectedTool);
+  const schema = tool?.inputSchema || {};
+  const properties = schema.properties || {};
+  const required = schema.required || [];
+
+  const handleFieldChange = (name, value) => {
+    setFormValues(prev => ({ ...prev, [name]: value }));
+  };
+
+  const handleToolChange = (e) => {
+    setSelectedTool(e.target.value);
+    reset();
+  };
+
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+
+    const args = {};
+    for (const [name, value] of Object.entries(formValues)) {
+      if (value !== '' && value !== undefined && properties[name]) {
+        args[name] = value;
+      }
+    }
+
+    callTool(selectedTool, args, 'Executing...');
+  };
+
+  return html`
+    <div class="explorer">
+      <form onSubmit=${handleSubmit}>
+        <${SelectField}
+          id="tool-select"
+          label="Select Tool"
+          value=${selectedTool}
+          onChange=${handleToolChange}
+          placeholder="-- Select Tool --"
+          options=${TOOLS.map(t => html`<option value=${t.name}>${t.name}</option>`)}
+        />
+        ${Object.entries(properties).map(([propName, propDef]) => html`
+          <${FormField}
+            key=${propName}
+            name=${propName}
+            propDef=${propDef}
+            required=${required.includes(propName)}
+            value=${formValues[propName] ?? (propName === 'limit' ? 20 : '')}
+            onChange=${handleFieldChange}
+            toolName=${selectedTool}
+          />
+        `)}
+        <button type="submit" class="btn-execute" disabled=${result.loading}>Execute</button>
+      </form>
+      <${ResultArea} result=${result} />
+    </div>
+  `;
+}
+
+// Topics Explorer component
+function TopicsExplorer() {
+  const [selectedTopic, setSelectedTopic] = useState('');
+  const { result, callTool, reset } = useMcpToolCall();
+
+  const handleChange = (e) => {
+    const value = e.target.value;
+    setSelectedTopic(value);
+    if (value) {
+      callTool('cf_get_topic', { name: value }, 'Loading topic...');
+    } else {
+      reset();
+    }
+  };
+
+  return html`
+    <div class="explorer">
+      <${SelectField}
+        id="topic-select"
+        label="Select Topic"
+        value=${selectedTopic}
+        onChange=${handleChange}
+        placeholder="-- Select a topic --"
+        options=${renderTopicOptions()}
+      />
+      <${ResultArea} result=${result} />
+    </div>
+  `;
+}
+
+// Mount components
+render(html`<${ToolExplorer} />`, document.getElementById('tool-explorer-root'));
+render(html`<${TopicsExplorer} />`, document.getElementById('topics-explorer-root'));
+
+// Render changelog
+const changelogEl = document.getElementById('changelog-content');
+if (changelogEl && CHANGELOG) {
+  changelogEl.innerHTML = marked.parse(CHANGELOG);
+}

data/lib/cf/mcp/templates/style.css

@@ -0,0 +1,165 @@
+* { box-sizing: border-box; }
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  line-height: 1.6;
+  max-width: 800px;
+  margin: 0 auto;
+  padding: 2rem;
+  background: #0d1117;
+  color: #c9d1d9;
+}
+h1 { color: #58a6ff; margin-bottom: 0.5rem; }
+h2 { color: #58a6ff; margin-top: 2rem; border-bottom: 1px solid #30363d; padding-bottom: 0.5rem; }
+a { color: #58a6ff; }
+code {
+  background: #161b22;
+  padding: 0.2rem 0.4rem;
+  border-radius: 4px;
+  font-size: 0.9em;
+}
+pre {
+  background: #161b22;
+  padding: 1rem;
+  border-radius: 8px;
+  overflow-x: auto;
+  border: 1px solid #30363d;
+}
+pre code { background: none; padding: 0; }
+.stats {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
+  gap: 1rem;
+  margin: 1rem 0;
+}
+.stat {
+  background: #161b22;
+  padding: 1rem;
+  border-radius: 8px;
+  text-align: center;
+  border: 1px solid #30363d;
+}
+.stat-value { font-size: 2rem; font-weight: bold; color: #58a6ff; }
+.stat-label { color: #8b949e; font-size: 0.9rem; }
+.endpoint {
+  background: #161b22;
+  padding: 1rem;
+  border-radius: 8px;
+  margin: 0.5rem 0;
+  border: 1px solid #30363d;
+}
+.endpoint-path { font-weight: bold; color: #7ee787; }
+.endpoint-desc { color: #8b949e; margin-top: 0.25rem; }
+.tools { margin: 1rem 0; }
+.tool {
+  background: #161b22;
+  padding: 0.75rem 1rem;
+  border-radius: 8px;
+  margin: 0.5rem 0;
+  border: 1px solid #30363d;
+}
+.tool-name { font-weight: bold; color: #ffa657; }
+.tool-desc { color: #8b949e; font-size: 0.9rem; }
+.explorer {
+  background: #161b22;
+  border: 1px solid #30363d;
+  border-radius: 8px;
+  padding: 1.5rem;
+  margin: 1rem 0;
+}
+.form-group {
+  margin-bottom: 1rem;
+}
+.form-label {
+  display: block;
+  margin-bottom: 0.25rem;
+  color: #c9d1d9;
+  font-size: 0.9rem;
+}
+.form-label .required {
+  color: #f85149;
+}
+.form-input, .form-select {
+  width: 100%;
+  padding: 0.5rem 0.75rem;
+  background: #0d1117;
+  border: 1px solid #30363d;
+  border-radius: 6px;
+  color: #c9d1d9;
+  font-size: 0.9rem;
+}
+.form-input:focus, .form-select:focus {
+  outline: none;
+  border-color: #58a6ff;
+  box-shadow: 0 0 0 3px rgba(88, 166, 255, 0.3);
+}
+.form-input::placeholder {
+  color: #6e7681;
+}
+.form-hint {
+  font-size: 0.8rem;
+  color: #6e7681;
+  margin-top: 0.25rem;
+}
+.btn-execute {
+  background: #238636;
+  color: #fff;
+  border: none;
+  padding: 0.75rem 1.5rem;
+  border-radius: 6px;
+  font-size: 1rem;
+  cursor: pointer;
+  font-weight: 500;
+}
+.btn-execute:hover {
+  background: #2ea043;
+}
+.btn-execute:disabled {
+  background: #21262d;
+  color: #6e7681;
+  cursor: not-allowed;
+}
+.result-area {
+  background: #0d1117;
+  border: 1px solid #30363d;
+  border-radius: 6px;
+  padding: 1rem;
+  margin-top: 1rem;
+  word-wrap: break-word;
+  font-size: 0.9rem;
+  max-height: 400px;
+  overflow-y: auto;
+  display: none;
+}
+.result-area.visible {
+  display: block;
+}
+.result-area.error {
+  border-color: #f85149;
+  color: #f85149;
+}
+.result-area.success {
+  border-color: #238636;
+}
+.loading {
+  color: #6e7681;
+  font-style: italic;
+}
+/* Markdown content styles */
+.result-area h1 { font-size: 1.4em; color: #58a6ff; margin: 0 0 0.5em 0; border-bottom: 1px solid #30363d; padding-bottom: 0.3em; }
+.result-area h2 { font-size: 1.2em; color: #58a6ff; margin: 1em 0 0.5em 0; }
+.result-area h3 { font-size: 1.1em; color: #58a6ff; margin: 1em 0 0.5em 0; }
+.result-area p { margin: 0.5em 0; }
+.result-area strong { color: #ffa657; }
+.result-area code { background: #21262d; padding: 0.15em 0.3em; border-radius: 3px; font-size: 0.9em; }
+.result-area pre { background: #21262d; padding: 0.75em; border-radius: 6px; overflow-x: auto; margin: 0.5em 0; }
+.result-area pre code { background: none; padding: 0; }
+.result-area table { border-collapse: collapse; width: 100%; margin: 0.5em 0; }
+.result-area th, .result-area td { border: 1px solid #30363d; padding: 0.4em 0.6em; text-align: left; }
+.result-area th { background: #21262d; color: #58a6ff; }
+.result-area ul, .result-area ol { margin: 0.5em 0; padding-left: 1.5em; }
+.result-area li { margin: 0.25em 0; }
+.result-area a { color: #58a6ff; }
+.result-area dl { margin: 0.5em 0; }
+.result-area dt { color: #c9d1d9; margin-top: 0.75em; padding-bottom: 0.25em; border-bottom: 1px solid #21262d; }
+.result-area dt:first-child { margin-top: 0; }
+.result-area dd { margin: 0.25em 0 0 1em; color: #8b949e; }

data/lib/cf/mcp/tools/find_related.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module CF
+  module MCP
+    module Tools
+      class FindRelated < ::MCP::Tool
+        tool_name "cf_find_related"
+        description "Find all items related to a given Cute Framework item (bidirectional relationship search)"
+
+        input_schema(
+          type: "object",
+          properties: {
+            name: {type: "string", description: "Name of the item to find relations for (e.g., 'CF_Sprite', 'cf_make_sprite')"}
+          },
+          required: ["name"]
+        )
+
+        def self.call(name:, server_context: {})
+          index = server_context[:index]
+          return error_response("Index not available") unless index
+
+          item = index.find(name)
+          return text_response("Not found: '#{name}'") unless item
+
+          # Forward references: items this item references
+          forward_refs = (item.related || []).map { |ref_name|
+            ref_item = index.find(ref_name)
+            if ref_item
+              "- `#{ref_item.name}` (#{ref_item.type}) — #{ref_item.brief}"
+            else
+              "- `#{ref_name}` (not found in index)"
+            end
+          }
+
+          # Back references: items that reference this item
+          back_refs = []
+          index.items.each_value do |other_item|
+            next if other_item.name == name
+            next unless other_item.related&.include?(name)
+
+            back_refs << "- `#{other_item.name}` (#{other_item.type}) — #{other_item.brief}"
+          end
+
+          if forward_refs.empty? && back_refs.empty?
+            return text_response("# #{name}\n\nNo related items found.\n\n**Tip:** Not all items have explicit relationships documented.")
+          end
+
+          lines = ["# Related items for #{name}", ""]
+
+          unless forward_refs.empty?
+            lines << "## References (items this references)"
+            lines.concat(forward_refs)
+            lines << ""
+          end
+
+          unless back_refs.empty?
+            lines << "## Referenced by (items that reference this)"
+            lines.concat(back_refs)
+            lines << ""
+          end
+
+          text_response(lines.join("\n"))
+        end
+
+        def self.text_response(text)
+          ::MCP::Tool::Response.new([{type: "text", text: text}])
+        end
+
+        def self.error_response(message)
+          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
+        end
+      end
+    end
+  end
+end

data/lib/cf/mcp/tools/get_details.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module CF
+  module MCP
+    module Tools
+      class GetDetails < ::MCP::Tool
+        tool_name "cf_get_details"
+        description "Get detailed documentation for a specific Cute Framework item by exact name"
+
+        input_schema(
+          type: "object",
+          properties: {
+            name: {type: "string", description: "Exact name of the item (e.g., 'cf_make_app', 'CF_Sprite', 'CF_PlayDirection')"}
+          },
+          required: ["name"]
+        )
+
+        NAMING_TIP = "**Tip:** Cute Framework uses `cf_` prefix for functions and `CF_` prefix for types (structs/enums)."
+
+        def self.call(name:, server_context: {})
+          index = server_context[:index]
+          return error_response("Index not available") unless index
+
+          item = index.find(name)
+
+          if item.nil?
+            # Try a fuzzy search to suggest alternatives
+            suggestions = index.search(name, limit: 5)
+            if suggestions.empty?
+              text_response("Not found: '#{name}'\n\n#{NAMING_TIP}")
+            else
+              formatted = suggestions.map { |s| "- `#{s.name}` (#{s.type}) — #{s.brief}" }.join("\n")
+              text_response("Not found: '#{name}'\n\n**Similar items:**\n#{formatted}\n\n#{NAMING_TIP}")
+            end
+          else
+            output = item.to_text(detailed: true, index: index)
+
+            # Append related topics section for API items
+            if item.type != :topic
+              related_topics = index.topics_for(name)
+              if related_topics.any?
+                output += "\n\n## Related Topics\n"
+                output += related_topics.map { |t| "- **#{t.name}** — #{t.brief}" }.join("\n")
+                output += "\n\n**Tip:** Use `cf_get_topic` to read the full topic content."
+              end
+            end
+
+            text_response(output)
+          end
+        end
+
+        def self.text_response(text)
+          ::MCP::Tool::Response.new([{type: "text", text: text}])
+        end
+
+        def self.error_response(message)
+          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
+        end
+      end
+    end
+  end
+end

data/lib/cf/mcp/tools/get_topic.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "mcp"
+
+module CF
+  module MCP
+    module Tools
+      class GetTopic < ::MCP::Tool
+        tool_name "cf_get_topic"
+        description "Get the full content of a Cute Framework topic guide document"
+
+        input_schema(
+          type: "object",
+          properties: {
+            name: {type: "string", description: "Topic name (e.g., 'audio', 'collision', 'drawing', 'coroutines')"}
+          },
+          required: ["name"]
+        )
+
+        def self.call(name:, server_context: {})
+          index = server_context[:index]
+          return error_response("Index not available") unless index
+
+          topic = index.find(name)
+
+          if topic.nil? || topic.type != :topic
+            # Try fuzzy match on topic names
+            suggestions = index.topics.select { |t|
+              t.name.include?(name) || name.include?(t.name) || t.name.delete("_").include?(name.delete("_"))
+            }
+
+            if suggestions.empty?
+              text_response("Topic not found: '#{name}'\n\nUse `cf_list_topics` to see available topics.")
+            else
+              formatted = suggestions.map { |t| "- **#{t.name}** — #{t.brief}" }.join("\n")
+              text_response("Topic not found: '#{name}'\n\n**Similar topics:**\n#{formatted}")
+            end
+          else
+            text_response(topic.to_text(detailed: true, index: index))
+          end
+        end
+
+        def self.text_response(text)
+          ::MCP::Tool::Response.new([{type: "text", text: text}])
+        end
+
+        def self.error_response(message)
+          ::MCP::Tool::Response.new([{type: "text", text: "Error: #{message}"}], error: true)
+        end
+      end
+    end
+  end
+end